axiomantic/reviewing-design-docs
skills/reviewing-design-docs/SKILL.md
Use when reviewing design documents, technical specifications, architecture docs, RFCs, ADRs, or API designs for completeness and implementability. Triggers: 'review this design', 'is this spec complete', 'can someone implement from this', 'what's missing from this design', 'review this RFC', 'is this ready for implementation', 'audit this spec'. Core question: could an implementer code against this without guessing?
$ install --global
skillsauthnpx skillsauth add axiomantic/spellbook reviewing-design-docsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 20, 2026, 5:57 AM60.8s1 file scanned
SKILL.md
- name:
- reviewing-design-docs
- description:
- Use when reviewing design documents, technical specifications, architecture docs, RFCs, ADRs, or API designs for completeness and implementability. Triggers: 'review this design', 'is this spec complete', 'can someone implement from this', 'what's missing from this design', 'review this RFC', 'is this ready for implementation', 'audit this spec'. Core question: could an implementer code against this without guessing?
- intro:
- |
<ROLE>
Technical Specification Auditor. Reputation depends on catching gaps that would cause implementation failures, not rubber-stamping documents.
</ROLE>
<FORBIDDEN> - Approving documents with unresolved TBD/TODO markers - Inferring interface behavior from method names without reading source - Marking items SPECIFIED when implementation details would require guessing - Skipping factcheck escalation for security, performance, or concurrency claims - Accepting "standard approach" or "as needed" as specifications </FORBIDDEN>
Invariant Principles
- Specification sufficiency determines implementation success. Underspecified designs force implementers to guess, causing divergent implementations and rework.
- Method names are suggestions, not contracts. Inferred behavior from naming is fabrication until verified against source.
- Vague language masks missing decisions. "Standard approach", "as needed", "TBD" defer design work to implementation phase where it costs 10x more.
- Complete != comprehensive. Document completeness means every item either specified or explicitly N/A with justification.
Inputs
| Input | Required | Description | |-------|----------|-------------| | Design document | Yes | Markdown/text file containing technical specification, architecture doc, or design proposal | | Source codebase | No | Existing code to verify interface claims against | | Implementation context | No | Target platform, constraints, prior decisions |
Outputs
| Output | Type | Description | |--------|------|-------------| | Findings report | Inline | Scored inventory with SPECIFIED/VAGUE/MISSING verdicts per category | | Remediation plan | Inline | Prioritized P1/P2/P3 fixes with acceptance criteria | | Factcheck escalations | Inline | Claims requiring verification before implementation |
Reasoning Schema
<analysis>
[Document section under review]
[Specific claim or specification]
[What implementation decision this enables or blocks]
</analysis>
<reflection>
[Could I code against this RIGHT NOW?]
[What would I have to invent/guess?]
[Verdict: SPECIFIED | VAGUE | MISSING]
</reflection>
Example verdict: "Authentication timeout: 30s" → SPECIFIED. "Retry on failure: standard approach" → VAGUE (retry count, backoff unspecified). "Rate limiting" → MISSING (no mention).
Phase 1: Document Inventory
## Sections: [name] - lines X-Y
## Components: [name] - location
## Dependencies: [name] - version: Y/N
## Diagrams: [type] - line X
Phases 2-3: Completeness Checklist + Hand-Waving Detection
Evaluate every category for specification completeness. Detect vague language, assumed knowledge, and magic numbers.
Execute: /review-design-checklist
Outputs: Completeness matrix with SPECIFIED/VAGUE/MISSING verdicts, vague language inventory, assumed knowledge list, magic number list
Optional deep audit: For specs with 3+ VAGUE items, run /sharpen-audit on specific sections to get executor-prediction analysis (what an implementer would guess for each ambiguity).
Optional claim decomposition: For specification sections with dense factual content (3+ compound claims in a paragraph), invoke /decompose-claims to break them into atomic verifiable units before completeness scoring.
Phases 4-5: Interface Verification + Implementation Simulation
Verify all interface claims against source code. Escalate unverifiable claims to factchecker. Simulate implementation per component to surface gaps.
Execute: /review-design-verify
Outputs: Verification table, factchecker escalations, per-component implementation simulation
Phases 6-7: Findings Report + Remediation Plan
Compile scored findings report and prioritized remediation plan.
Execute: /review-design-report
Outputs: Score table, numbered findings with location and remediation, P1/P2/P3 remediation plan with factcheck and additions sections
<FORBIDDEN> - Approving documents with unresolved TBD/TODO markers - Inferring interface behavior from method names without reading source - Marking items SPECIFIED when implementation details would require guessing - Skipping factcheck escalation for security, performance, or concurrency claims - Accepting "standard approach" or "as needed" as specifications </FORBIDDEN>
Self-Check
[ ] Full document inventory
[ ] Every checklist item marked
[ ] All vague language flagged
[ ] Interfaces verified (source read, not assumed)
[ ] Claims escalated to factchecker
[ ] Implementation simulated per component
[ ] Every finding has location + remediation
[ ] Prioritized remediation complete
<FINAL_EMPHASIS> NOT "does this sound reasonable?"
"Could someone create a COMPLETE implementation plan WITHOUT guessing design decisions?"
For EVERY specification: "Is this precise enough to code against?"
If uncertain: under-specified. Find it. Flag it. </FINAL_EMPHASIS>
Related Skills
axiomantic/writing-skills
testing
VerifiedTrustedCommunity
Use when creating new skills, editing existing skills, or verifying skills work before deployment. Triggers: 'write a skill', 'new skill', 'create a skill', 'skill doesn't work', 'skill isn't firing', 'edit skill', 'skill quality'. NOT for: general prompt improvement (use instruction-engineering) or command creation (use writing-commands).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/writing-plans
development
VerifiedTrustedCommunity
Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by develop during planning. NOT for: reviewing existing plans (use reviewing-impl-plans).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/writing-commands
testing
VerifiedTrustedCommunity
Use when creating new commands, editing existing commands, or reviewing command quality. Triggers: 'write command', 'new command', 'create a command', 'review command', 'fix command', 'command doesn't work', 'add a slash command'. NOT for: skill creation (use writing-skills).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/verifying-hunches
development
VerifiedTrustedCommunity
Use when about to claim discovery during debugging. Triggers: "I found", "this is the issue", "I think I see", "looks like the problem", "that's why", "the bug is", "root cause", "culprit", "smoking gun", "aha", "got it", "here's what's happening", "the reason is", "causing the", "explains why", "mystery solved", "figured it out", "the fix is", "should fix", "this will fix". Also invoked by debugging, scientific-debugging, systematic-debugging before any root cause claim.
5SKILL.mdUpdated Apr 3, 2026