design-doc-review
Skill3 starsChanged 7 months agoMITView on GitHub
Expert architect-level review system that takes a software design document and systematically refines, reworks, and hardens it into a foolproof implementation blueprint with no blind spots. Runs a multi-phase pipeline: ingest, structural audit, technical deep dive, continuity check, gap analysis with autoheal, adversarial final review, and hardened output. Activates when the user says "review this design doc", "harden this design", "audit this spec", "review my architecture", "design doc review", or when the user provides a software design document and asks for feedback, critique, improvements, or validation. Also activate when the user uploads a technical spec, RFC, architecture doc, or system design and wants it improved, stress-tested, or made implementation-ready. Use this skill even when the user simply says "review this" and the input is clearly a software design document.
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 82
Every phase MUST include a brief plain-English description of what's happening and why before showing results.
- Distinctive: line 96
Not every document needs the same scrutiny.
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design Doc Review
Takes a software design document at any maturity level and systematically hardens it into an implementation-ready blueprint. The philosophy: design everything up front. Every decision deferred to implementation is a bug, scope creep vector, or miscommunication waiting to happen.
When to activate
Manual triggers: "review this design doc", "harden this design", "audit this spec", "review my architecture", "design doc review", "make this implementation-ready", "stress test this spec", "is this spec complete?", "what's missing from this design?"
Auto-detect: User provides a software design document and asks for feedback, critique, or improvements; user uploads a technical spec, RFC, or architecture doc and asks "is this ready to build?"
Do NOT activate when:
- User wants a design written from scratch (use
interrogate+architect-plan-for-dispatch) - User wants a code review, not a design review
- The document is not a software design (business plan, marketing doc)
- User says "just give me quick feedback" — give conversational feedback instead
Input
Any form of software design document: formal RFC, informal spec, ADR, technical proposal, system design with diagrams, partial designs. The skill calibrates review depth to the document's maturity (see reference/calibration-and-rules.md).
The seven-phase pipeline
Each phase produces visible output. Never skip a phase. Run them in order. Full detail for each phase: reference/phases.md.
| Phase | Purpose | Output |
| 1. Ingest and Comprehend | Build mental model, calibration checkpoint | System summary, components, design intent — wait for user confirmation |
| 2. Structural Audit | Check completeness against 16-point checklist | Per-section status (STRONG / WEAK / MISSING), structural score |
| 3. Technical Deep Dive | Evaluate quality across 6 dimensions | Findings ordered by severity (CRITICAL / HIGH / MEDIUM / LOW) |
| 4. Continuity and Consistency | Cross-reference all sections for contradictions | Contradictions list, terminology inconsistencies, continuity score |
| 5. Gap Analysis and Autoheal | Draft missing content, resolve contradictions | Autohealed sections marked inline, decisions flagged for author |
| 6. Adversarial Final Review | Five kill-question stress test | Per-question SURVIVES / PARTIALLY / FAILS, final verdict |
| 7. Hardened Output | Assemble final deliverable | Scorecard + hardened document + changelog |
The 16-point structural checklist used in Phase 2 is its own reference: reference/canonical-checklist.md.
Workflow checklist
Copy this into your response and check off as you progress:
Design doc review pipeline:
- [ ] Phase 1: Ingest and Comprehend (calibration confirmed by user)
- [ ] Phase 2: Structural Audit
- [ ] Phase 3: Technical Deep Dive
- [ ] Phase 4: Continuity and Consistency
- [ ] Phase 5: Gap Analysis and Autoheal
- [ ] Phase 6: Adversarial Final Review
- [ ] Phase 7: Hardened Output (scorecard + document + changelog)Process transparency
Every phase MUST include a brief plain-English description of what's happening and why before showing results. Write as if you're a senior architect walking a colleague through your review. Don't just dump tables and scores — explain what you're looking for, why it matters, and what you found.
Example lead-in (Phase 3):
"Now I'm going through the actual design quality. Phase 2 told us what's missing from the document — this phase tells us what's wrong with what IS there. I'm reading each component with the question: if I had to implement this tomorrow, would I have enough information to build it correctly?"
Calibrating review depth
Not every document needs the same scrutiny. Match depth to maturity:
| Document maturity | Phase 2 | Phase 3 | Phase 4 | Phase 5 | Phase 6 |
| Napkin sketch | Heavy | Light | Skip | Heavy (draft missing) | Quick sanity |
| Draft | Full | Calibrated | Full | Big gaps only | Full |
| Review-ready | Full | Exhaustive | Full | Full | Genuinely adversarial |
| Near-final | Light | Heavy | Heavy (devil in details) | Targeted | Primary value |
Full guidance and the 8 review rules: reference/calibration-and-rules.md.
Examples
- Good vs. bad findings (specific vs. vague): examples/findings.md
- How to chain with other skills: examples/chaining.md
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- blackmichael/agent-skills★ 3same name
- jamestexas/agents★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository98 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-architectSkill
- architect-plan-for-dispatchSkill
- automate-auditSkill
- brain-dumpSkill
- chat-to-code-promptSkill
- cli-apifySkill
- cli-batSkill
- cli-duckdbSkill
- cli-fdSkill
- cli-ffmpegSkill
- cli-fzfSkill
- cli-ghSkill
- cli-httpieSkill
- cli-imagemagickSkill
- cli-jqSkill
- cli-lazygitSkill
- cli-pandocSkill
- cli-playwrightSkill
- cli-ripgrepSkill
- cli-sqliteSkill
- cli-yqSkill
- cli-yt-dlpSkill
- codebase-reviewSkill
- context-summarySkill
- decomposeSkill
- delegateSkill
- design-a-systemSkill
- devils-advocateSkill
- gh-repo-createSkill
- ig-savesSkill
- interrogateSkill
- mentor-aristotleSkill
- mentor-attiaSkill
- mentor-aureliusSkill
- mentor-bloomSkill
- mentor-brownSkill
- mentor-buffettSkill
- mentor-builderSkill
- mentor-carnegieSkill
- mentor-clearSkill
- mentor-councilSkill
- mentor-cunninghamSkill
- mentor-dalioSkill
- mentor-davinciSkill
- mentor-demingSkill
- mentor-ferrissSkill
- mentor-feynmanSkill
- mentor-franklSkill
- mentor-garyveeSkill
- mentor-godinSkill
- mentor-gogginsSkill
- mentor-greeneSkill
- mentor-holidaySkill
- mentor-hormoziSkill
- mentor-houselSkill
- mentor-jockoSkill
- mentor-jungSkill
- mentor-kahnemanSkill
- mentor-kingSkill
- The first 60 shown.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.