tech-spec:review

Review Technical Specification

Inputs

Ask the user to provide:

• Tech spec: Path to the specification file, or pasted content
• Focus areas (optional): Specific concerns to prioritize (e.g., "security", "API design")
• Repositories (optional): Codebases to consult when verifying spec claims

Code Exploration

When repositories are provided, consult code to verify:

• Proposed patterns match existing conventions
• Referenced files and structures exist
• Implementation assumptions are accurate

Explore on demand during review rather than upfront.

Review Process

Identify Expert Perspectives

Select relevant personas from references/experts.md:

• Always include standard personas (security, API, database, etc.)
• Add dynamic personas based on spec content (integrations, analytics, etc.)
• User-specified focus areas get priority

Conduct Review

For each relevant persona:

1. Scan the spec for areas within their expertise
2. Identify findings: gaps, risks, unclear decisions, missing considerations
3. Rate severity: blocking, important, or nice-to-have

Present Findings

Group related findings into batches and present via AskUserQuestion:

• Batch by persona or topic when findings cluster naturally
• Present individually when no natural grouping exists
• Include severity and recommendations

Interview for Resolution

For findings with meaningful trade-offs:

• Discuss alternatives with the user
• Capture decisions in the Design Decisions table
• Update the spec with resolutions

Update Spec

Apply agreed changes directly to the spec file:

• Add missing sections or considerations
• Expand the Design Decisions table
• Clarify ambiguous areas