Spec Review Modes

Use this skill to review technical specs without collapsing into one vague style of feedback.

Core rule

Always choose one primary mode first. You may add a short secondary pass later, but do not blur all three into one undifferentiated review.

The three modes are:

• Mode A — Quick Overview
• Mode B — Strict Spec Audit
• Mode C — Product / Architecture Lens

If the user does not choose, infer from intent:

• Wants a fast scan / first impression / "先看有沒有大問題" → Mode A
• Wants contradictions / ownership / API / type rigor → Mode B
• Wants product depth / market sense / "這樣會不會太薄" → Mode C

For detailed checklists and output scaffolds, read references/review-checklists.md.

Before reading

1. Identify the root folder or top-level doc set.
2. Read directory structure first if the spec is multi-file.
3. Read overview.md and schema-v0.md first when present.
4. If there is a shared type file (shared-types.md or equivalent), read it before criticizing type drift.
5. Do not pretend to have read everything if you only sampled part of the stack.

Mode A — Quick Overview

Use this when the goal is speed and orientation.

Focus on:

• what the system is trying to do
• whether the boundaries make sense
• the most obvious strengths
• the most dangerous ambiguities
• what to read next

Do:

• summarize the stack in plain language
• name the 2-5 biggest risks, not every nit
• point out where the docs feel clean vs muddy
• say what is missing only if it blocks understanding

Do not:

• enumerate every schema concern
• nitpick naming unless it causes real confusion
• drift into implementation planning unless asked

Mode B — Strict Spec Audit

Use this when the goal is rigor.

Focus on:

• type consistency
• noun drift
• lifecycle ownership
• API boundary clarity
• read/write model separation
• duplicated truth sources
• unresolved canonical source questions

Default audit questions:

• Are canonical nouns defined in one place?
• Do shared types and downstream specs agree?
• Is lifecycle ownership centralized or leaking across contexts?
• Are APIs placed in the correct bounded context?
• Is any read-side module coupled to storage shape?
• Are there hidden transitions or implicit authority assumptions?
• Are there contradictory examples, tables, or state diagrams?

When you find problems, classify them:

• Must fix — will cause implementation drift or broken ownership
• Should fix — clarity/maintainability problem, not fatal
• Future concern — acceptable deferral, but note it

Mode C — Product / Architecture Lens

Use this when the question is not just "is the spec coherent?" but "does this system become valuable, thick, and usable?"

Focus on:

• whether the spec creates real product pressure or only completeness
• whether the system will change behavior in workflows
• whether the abstractions are too early or too internal
• whether the spec is building something that feels alive/useful vs merely tidy
• where the user-facing leverage actually comes from

Default product/architecture questions:

• What real pain does this spec solve?
• Which parts create product thickness versus internal neatness?
• What would a user actually feel from this system?
• Which parts are entry points, and which should stay buried as substrate?
• Is this creating first-order value or second-order optimization?
• Does the spec over-index on architecture completeness?

Do not reduce this mode to market fluff. Stay anchored to the documents.

Review method for multi-file stacks

For a spec tree like:

• decision-model/
• decision-intake/
• decision-injection/
• decision-governance/

Use this order unless the user says otherwise:

1. model/shared types
2. write/intake
3. read/injection
4. governance/lifecycle

Reason: you need canonical nouns before you criticize downstream seams.

Good output shape

For Mode A

• 1 short paragraph: what this stack is
• strengths
• biggest risks
• what to read/fix next

For Mode B

• overall judgment
• must-fix list
• should-fix list
• future concerns
• boundary/ownership summary

For Mode C

• what feels product-thick
• what feels internally tidy but externally thin
• what the actual wedge is
• what should remain hidden substrate
• conclusion

Important discipline

• Do not say "everything looks good" unless it truly does.
• Do not inflate minor wording issues into architectural crises.
• Do not confuse a complete spec with a useful product.
• Do not review all files at the same level of detail if some are canonical and others derivative.
• Ground criticism in concrete files, nouns, tables, or transitions.

Optional combined workflow

If the user wants a deeper pass, use this sequence:

1. Mode A to orient
2. Mode B to identify structural faults
3. Mode C to judge whether the resulting system is worth building as framed

Do not start with Mode C before you understand the structure.