From code-harness-skills
Create design documents in the correct format and location. Use when user asks to create a design doc, plan a feature, or document a design. Handles both planned/ and implemented/ docs with proper structure.
How this skill is triggered — by the user, by Claude, or both
Slash command
/code-harness-skills:design-doc-creatorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create well-structured design documents for features following project conventions.
Create well-structured design documents for features following project conventions.
| Environment Variable | Default | Description |
|---|---|---|
DESIGN_DOCS_DIR | design_docs | Root directory for design documents |
CHANGELOG_PATH | CHANGELOG.md | Path to changelog file |
VERSION_FILE | VERSION | Path to version file (for auto-detecting current version) |
Most common usage:
# User says: "Create a design doc for better error messages"
# This skill will:
# 1. Search for related existing design docs
# 2. Create ${DESIGN_DOCS_DIR:-design_docs}/planned/better-error-messages.md
# 3. Fill template with proper structure
Invoke this skill when:
scripts/create_planned_doc.sh <doc-name> [version]Create a new design document in ${DESIGN_DOCS_DIR}/planned/.
Usage:
# Create doc in planned/ root (no version)
scripts/create_planned_doc.sh m-dx2-better-errors
# Create doc in next version folder
scripts/create_planned_doc.sh reflection-system v1_2_0
What it does:
scripts/move_to_implemented.sh <doc-name> <version>Move a design document from planned/ to implemented/ after completion.
Usage:
scripts/move_to_implemented.sh m-dx1-developer-experience v1_0_0
1. Gather Requirements
Ask user:
CRITICAL: Audit for Systemic Issues FIRST
Before writing a design doc for a bug fix, ALWAYS ask: "Is this part of a larger pattern?"
The Anti-Pattern (incremental special-casing):
v1: Add feature for case A
v2: Bug! Add special case for B
v3: Bug! Add special case for C
...forever patching
The Pattern to Follow (unified solutions):
v1: Bug report for case B
BEFORE writing design doc:
1. Search for similar code paths
2. Check if A, C, D have same gap
3. Design ONE fix covering ALL cases
v2: Unified fix - no future bugs in this area
Analysis Checklist (do BEFORE writing design doc):
Warning Signs of Fragmented Design:
handleX, handleY, handleZ instead of unified handle|| specialCase conditions2. Choose Document Name
Naming conventions:
feature-name.mdm-XXX-feature-name.mdimprovements.md3. Run Create Script
# If version is known
scripts/create_planned_doc.sh feature-name v1_2_0
# If version not decided yet
scripts/create_planned_doc.sh feature-name
4. Customize the Template
Fill in all sections: header metadata, problem statement, goals, solution design, examples, success criteria, testing strategy, timeline, risks.
5. Review and Commit
git add ${DESIGN_DOCS_DIR:-design_docs}/planned/feature-name.md
git commit -m "Add design doc for feature-name"
When to move:
scripts/move_to_implemented.sh feature-name v1_0_0
See resources/design_doc_structure.md for:
Use metrics, not vague statements. "Reduce build time from 7.5h to 2.5h (-67%)" not "Make development easier."
Quantify current state and target improvements with real numbers.
Use checkboxes, estimated hours, and clear definitions of done.
Reference real code, existing implementations, and prior art.
2x your initial estimate. Include buffer for testing and documentation.
${DESIGN_DOCS_DIR:-design_docs}/
├── planned/ # Future features
│ ├── feature.md # Unversioned (version TBD)
│ └── v1_2_0/ # Targeted for v1.2.0
│ └── feature.md
└── implemented/ # Completed features
├── v1_0_0/ # Shipped in v1.0.0
│ └── feature.md
└── v1_1_0/ # Shipped in v1.1.0
└── feature.md
Version folder naming:
v1_0_0 not v1.0.0This skill loads information progressively:
resources/design_doc_structure.md (detailed guide)npx claudepluginhub 8-bit-sheep/code-harness-skills --plugin agent-inboxTechnical design documents — problem analysis, solution exploration, architectural decisions. Invoke whenever task involves any interaction with design documents — creating, updating, reviewing, comparing options, or capturing architectural decisions.
Suggests and scaffolds org-mode design documents for significant changes, new features, architectural decisions, or tradeoffs. Converts existing markdown docs to org-mode and queues tasks to backlog.
Saves design documents from planning sessions with branch tracking, revision chains, and cross-session discoverability.