Review spec

Review a Design Specification

Review a design specification against the actual codebase to surface inaccuracies, missing details, convention violations, and potential issues — before implementation begins. The goal is to catch problems that would cause confusion or rework during implementation.

Spec to review: $ARGUMENTS

If no specific spec is given, ask the user which spec in Specs/ they'd like reviewed.

Process

1. Read the Spec

Read the full spec file. As you read, collect:

• Referenced files: Every source file mentioned (implementation touchpoints, code examples, "see also" references)
• Factual claims: Specific assertions about existing code (option names/defaults, function signatures, symbol locations, data structures, file paths)
• New additions: Symbols, options, files, or behaviors the spec proposes to add
• Behavioral descriptions: How existing functions work, what they accept, what they return

2. Cross-Reference with the Codebase

Read all referenced files in parallel using the Explore agent or direct reads. For each file, verify:

• Options and signatures: Do the current options match what the spec claims? Are default values correct? Does the spec list all required changes?
• Symbol locations: Are symbols declared where the spec says they should be (e.g., CommonSymbols.wl vs private context)? Follow existing conventions — if similar symbols are private in other files, new ones should be too.
• Function behavior: Does the code actually work the way the spec describes? Look at the actual implementation, not just the signature.
• Naming and conventions: Do proposed names follow codebase conventions (lowerCamelCase for internal functions, UpperCamelCase for exported, etc.)?
• Implementation touchpoints completeness: Are there files that would need changes but aren't listed? For example, if a new path variable is added, does it need a declaration in CommonSymbols.wl AND a definition in Files.wl?

3. Check for Common Issues

Look specifically for these categories of problems:

Factual inaccuracies:

• Option names or defaults that don't match the current code
• Function signatures that accept different arguments than described
• Symbols described as being in one location when they're in another
• Properties or features attributed to objects that don't exist yet

Missing touchpoints:

• Files that need changes but aren't listed in the implementation table
• Intermediate helpers or utilities the spec assumes exist but don't
• Test files, documentation, or configuration that should be updated

Vague or ambiguous language:

• "such as" or "e.g." where a concrete decision is needed
• Placeholder names that should be pinned down
• Underspecified behavior for edge cases (e.g., what happens with File[...] targets?)

Logical and ordering issues:

• Operations that could fail partway through, leaving inconsistent state
• Missing error handling
• Race conditions or atomicity concerns in multi-step operations

Convention violations:

• Symbols proposed for shared contexts that are only used in one file (should be private)
• Patterns that diverge from how similar features are already implemented
• Error handling that doesn't follow the project's Enclose/Confirm/throwFailure patterns

4. Triage and Act

For each issue found, decide:

• Straightforward fix (wrong default value, vague language, missing file in touchpoints table): Edit the spec directly to correct it.
• Needs discussion (design trade-offs, ordering concerns, architectural decisions): Present the issue clearly with the trade-offs so the user can decide.

Focus on the top three issues by importance. If there are more, mention them briefly but don't overwhelm. Importance is determined by how much implementation pain the issue would cause if left uncorrected.

5. Report

For each issue addressed:

• State what the issue is
• Explain why it matters (what would go wrong during implementation)
• Show what you changed (for fixes) or present the options (for discussions)

If no significant issues are found, say so — then consider whether the spec could be improved in other ways (clarity, readability, completeness of examples).