Comments

Deep dive on the %% comment %% syntax - the core feedback mechanism.

Basic Syntax

%% Your comment here %%

Comments are wrapped in double percent signs. They can appear anywhere in a document.

Types of Comments

General Feedback

Plain comments without prefixes:

%% This section needs more detail %%
%% The timeline seems unrealistic %%
%% Consider adding examples %%

Questions

Prefix with ?: to mark as a question:

%% ?: Is 15 minutes too short for session timeout? %%
%% ?: Should we support annual billing? %%

Questions signal that you need input before proceeding.

Information Tags

INFO - Actionable information Claude should use:

%% INFO: Budget increased to $200/month %%
%% INFO: API v2 released with breaking changes %%

NOTE - Historical context (read-only, no response needed):

%% NOTE: Team decided this in Dec 10 meeting %%
%% NOTE: We tried Redis but had memory issues %%

NOTEs are absorbed, not ignored. While Claude won’t respond directly to NOTEs, they become part of the context that shapes subsequent behavior. A NOTE like “I prefer proposals before implementation” may subtly influence how Claude approaches later requests — though this effect is not guaranteed and may fade as context shifts or is compressed in long conversations.

Status Tags

Mark entire sections:

## Authentication %% APPROVED %%
## Payment Processing %% WIP %%
## Admin Panel %% REVISE %%
## Legacy Code %% NO: too complex for v1 %%

Tag	Meaning	Claude’s Action
`APPROVED`	Section is finalized	Don’t modify
`WIP`	Work in progress	Can modify
`REVISE`	Needs improvement	Look for related comments
`NO: reason`	Rejected	Remove content

Comment Placement

After Content

Most common - comment on what came before:

The session timeout is 15 minutes.

%% Too short - increase to 30 %%

Inline with Headers

Status tags work well after headers:

## Pricing %% APPROVED %%

Multiple Comments

You can have multiple comments in sequence:

%% This looks good overall %%
%% But the error handling needs work %%
%% Also consider edge cases %%

Responses

Claude responds with •%%> response <%%•:

%% This section needs more detail %%

•%%>Added specific metrics: 99.9% uptime SLA,
<100ms p95 latency, 10K req/s capacity. <%%•

Each comment gets its own response:

%% Is this the right approach? %%

•%%>Yes, this pattern is standard for auth flows. <%%•

%% What about token refresh? %%

•%%>Added refresh token handling in section below. <%%•

Team Attribution

Add initials to track who said what:

%% @JS: Can we simplify this? %%
%% @MK: APPROVED %%
%% @AL: Move to v2 roadmap %%

Or for group consensus:

%% @ALL: Team agreed on this approach %%

Best Practices

Be Specific

# Bad
%% Fix this %%

# Good
%% Change timeout from 15 to 30 minutes %%

One Topic Per Comment

# Bad
%% Fix timeout and add logging and update docs %%

# Good
%% Fix timeout - 15 → 30 minutes %%
%% Add request logging %%
%% Update API docs %%

Use Questions for Decisions

# When you need input
%% ?: Redis or Memcached for caching? %%

# When you have direction
%% Use Redis for caching %%

Common Patterns

Request Research

%% Research competitors' rate limits and recommend %%

Request Expansion

%% Add more detail on error handling %%

Request Simplification

%% This is over-engineered - simplify %%

Conditional Approval

%% APPROVED if we add input validation %%

Document Iteration Skill