Software_development_department design-review

When this skill is invoked:

1. Read the target design document in full.

2. Read the master CLAUDE.md to understand project context and standards.

3. Read related design documents referenced or implied by the target doc (check

   design/docs/

   for related systems).

4. Evaluate against the Design Document Standard checklist:

   • Has Overview section (one-paragraph summary)
   • Has User Fantasy section (intended feeling)
   • Has Detailed Rules section (unambiguous mechanics)
   • Has Formulas section (all math defined with variables)
   • Has Edge Cases section (unusual situations handled)
   • Has Dependencies section (other systems listed)
   • Has Tuning Knobs section (configurable values identified)
   • Has Acceptance Criteria section (testable success conditions)

5. Check for internal consistency:

   • Do the formulas produce values that match the described behavior?
   • Do edge cases contradict the main rules?
   • Are dependencies bidirectional (does the other system know about this one)?

6. Check for implementability:

   • Are the rules precise enough for a programmer to implement without guessing?
   • Are there any "hand-wave" sections where details are missing?
   • Are performance implications considered?

7. Check for cross-system consistency:

   • Does this conflict with any existing mechanic?
   • Does this create unintended interactions with other systems?
   • Is this consistent with the product's established tone and pillars?

8. Output the review in this format:

## Design Review: [Document Title]

### Completeness: [X/8 sections present]
[List missing sections]

### Consistency Issues
[List any internal or cross-system contradictions]

### Implementability Concerns
[List any vague or unimplementable sections]

### Balance Concerns
[List any obvious balance risks]

### Recommendations
[Prioritized list of improvements]

### Verdict: [APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED]

9. Contextual next step recommendations:
   • If the document being reviewed is

     product-concept.md

     or

     product-pillars.md

     :
     • Check if

       design/docs/systems-index.md

       exists
     • If it does NOT exist, add to Recommendations:

       "This concept is ready for systems decomposition. Run

       /map-systems

       to break it down into individual systems with dependencies and priorities, then write per-system PRDs."

   • If the document is an individual system PRD:
     • Check if the systems index references this system
     • If verdict is APPROVED: suggest "Update the systems index status for this system to 'Approved'."
     • If verdict is NEEDS REVISION or MAJOR REVISION NEEDED: suggest "Update the systems index status for this system to 'In Review'."
     • Note: This skill is read-only. The user (or

       /design-system

       ) must perform the actual status update in the systems index.

Protocol

• Question: Auto-starts from argument (path to design doc)
• Options: Skip — single review path
• Decision: Skip — verdict is advisory
• Draft: Full review shown in conversation only
• Approval: Skip — read-only; this skill never writes files

Output

Deliver exactly:

• Completeness score (X/8 required sections present)
• Consistency issues — contradictions or undefined terms (or "None")
• Implementability concerns — sections too vague to build from (or "None")
• Verdict:

  APPROVED

  /

  NEEDS REVISION

  /

  MAJOR REVISION NEEDED

• Next skill — one recommended follow-up (e.g.,

  /map-systems

  , update systems index)