shuymn/design-doc

Path Resolution

• <skill-root> means the directory containing this SKILL.md.
• Resolve scripts/... and references/... relative to <skill-root>, not the caller's current working directory.
• When executing local helpers, use explicit paths such as <skill-root>/scripts/....

Mode Dispatch

Determine the execution mode from $ARGUMENTS:

• If the first whitespace-separated token of $ARGUMENTS is exactly review, or $ARGUMENTS contains --review or mode=review → Review Mode: read references/review-mode.md and follow its instructions.
• Otherwise → Create Mode (default; continue to # Design Doc Creation)

Design Doc Creation

Create design documents through iterative dialogue with the user, capturing design decisions as Architecture Decision Records (ADRs).

Markdown Formatting Contract

• Never rely on soft line breaks for visible separation in rendered markdown.
• For key-value metadata, always use list or table syntax (preferred: - **Key**: value).

<HARD-GATE>

Do NOT take any of these actions until the design doc is explicitly approved by the user:

• Write any implementation code or scaffolding
• Invoke the decompose-plan skill
• Create an implementation plan
• Create any project files outside of docs/

Reason: premature artifacts create sunk-cost pressure that biases design feedback — it is far cheaper to change a design doc than to revert code written against an unapproved design.

No exceptions. Not even "just setting up the structure" or "a quick prototype to validate."

Lifecycle Contract for Breaking Changes

For breaking changes or staged migrations, the design doc must specify lifecycle closure, not only end-state architecture.

• Add a ## Compatibility & Sunset section.
• Add a Temporary Mechanism Index with stable IDs (TEMPxx) and lifecycle-record pointers.
• Add a Sunset Closure Checklist row for every TEMPxx (required even when lifecycle record details are in ADR).
• For each TEMPxx, choose a lifecycle record:
  • ADR (preferred when the mechanism includes design trade-offs or policy decisions)
  • In-doc ledger row (acceptable for small/local temporary mechanics)
• Every Temporary Mechanism Index row must define:
  • ID, Mechanism, Lifecycle Record, Status
• Every TEMPxx checklist row must define:
  • ID, Introduced for (why it exists)
  • Retirement trigger (objective condition)
  • Retirement verification (how closure is proven)
  • Removal scope (what is removed/disabled when retired)
• If tracked in ADR, link the ADR from Compatibility & Sunset and include a matching ADR Sunset Clause.
• Owner and Target milestone/date are required only when coordination or handoff risk exists (for solo development, keep them optional).
• Missing TEMPxx index row, checklist row, or closure fields is a design gap, not an implementation detail.
• TEMPxx IDs are lifecycle-governance artifacts; downstream planning should track them in trace artifacts, not as standalone task-list entries.

Decomposition Strategy Contract (Single vs Root/Sub)

Default to a single design doc. Use root/sub split only when structural conditions require it.

• Default: Split Decision: single
• Do not split only because the document is long.
• Record the decision in the design doc under ## Decomposition Strategy.
• Add ### Boundary Inventory for every design, even when Split Decision: single.
• ### Boundary Inventory must use exactly these columns: Boundary, Owns Requirements/AC, Primary Verification Surface, TEMP Lifecycle Group, Parallel Stream, Depends On.
• Use Owns Requirements/AC to record the owned ID range/summary for boundary-owned rows; use Integration-only for root-only integration rows.
• Use Parallel Stream values yes or no; use Depends On as comma-separated boundary names or none; use TEMP Lifecycle Group as a shared lifecycle label or none.

Split is required if any of these are true:

• Distinct domains/components have independent acceptance flows and verification commands.
• Staged migration or TEMPxx lifecycle differs by domain.
• Work is expected to proceed in parallel streams with clear ownership boundaries.
• A single doc cannot keep requirements -> tasks traceability unambiguous.

Split is discouraged (keep single) if any of these are true:

• Most requirements target one cohesive component boundary.
• Verification is primarily a single integrated flow.
• Proposed sub-doc boundaries would create many cross-boundary tasks.

If Split Decision: root-sub, require:

• Root doc with global scope, shared constraints, cross-domain dependencies, and integration acceptance criteria.
• One sub design doc per boundary with local requirements and acceptance criteria.
• Explicit boundary ownership (what each sub owns, and what remains integration-only).
• Root-level coverage table mapping root requirements/acceptance criteria to sub-doc owners or integration tasks.
• Every boundary-owned row in ### Boundary Inventory must map 1:1 to Sub-Doc Index Owned Boundary.

Codebase Constraint Contract (Required for Non-Greenfield)

When the design modifies existing behavior, APIs, runtime paths, or tests, do not treat design as greenfield.

• Add an ## Existing Codebase Constraints section in the design doc.
• Capture constraints in a stable table (constraint ID, source file/test, constraint, impact on design, required verification).
• Include existing-test assumptions that may require task-scope updates later (shared helpers, fixtures, implicit legacy paths).
• For design intent that restricts behavior to a single path, removes or replaces an existing capability, or mandates failure when a former path is attempted (replacement/removal/fail-closed semantics). Common keyword examples (not exhaustive): only, must not, remove, retire, no fallback, fail-closed, 唯一, 廃止, 禁止. Include both:
  • prohibited-path expectation (what must fail or disappear)
  • allowed-path expectation (what must work)
• If required constraints cannot be identified from current code/tests, stop as BLOCKED and request missing context before finalizing design.

Risk Classification Contract

Classify change areas by defect-impact severity. Risk tiers are defined by humans, not auto-inferred by agents. The tier definitions below describe semantic characteristics — the exact areas that qualify depend on the product and domain context.

| Tier | Semantic Characteristics | Downstream Effect | |------|-------------------------|-------------------| | Critical | A defect would cause irreversible damage, security breach, data loss, financial harm, or compliance violation. The blast radius extends beyond the immediate component to users, external systems, or regulatory boundaries. Common examples (not exhaustive): authentication, billing, access control, encryption, PII handling. | Change Rationale required. adversarial-verify mandatory after dod-recheck. | | Sensitive | A defect would silently corrupt state, break contractual interfaces, or require coordinated rollback across multiple components. The failure mode is typically delayed or hidden rather than immediately visible. Common examples (not exhaustive): DB schema, API contracts, state management, external integrations. | Change Rationale required. Heightened dod-recheck scrutiny applies. | | Standard | A defect would be caught by normal testing or cause a visible, locally-contained failure with straightforward rollback. Common examples (not exhaustive): feature components, tests, documentation, configuration. | Normal DoD verification. |

• Record classifications in ## Risk Classification section of the design doc.
• ## Risk Classification is mandatory when either condition is true:
  • Design is non-greenfield.
  • Design is greenfield but touches Critical domains (auth, billing, access control, encryption, PII).
• Critical and Sensitive areas must include Change Rationale in the structured format: Defect Impact: [what breaks on defect] / Blast Radius: [scope of impact].
• Standard areas must include semantic justification in the Change Rationale column using the format: Not Critical: [reason] / Not Sensitive: [reason].
• Confidence gate: If a Standard area's justification cannot be written, is generic, or is circular (e.g., "not critical because not important"), that area must be escalated to Sensitive or higher. Standard is not a default — it must be earned with explicit justification.
• Classifications propagate downstream: design-doc → decompose-plan (task-level tier inheritance) → execute-plan (verification intensity).

Scale-Appropriate Depth

Default to the Core Profile. Add sections only when triggered.

Core Profile (always include): Overview, Goals, Non-Goals, Proposed Solution, Detailed Design, Acceptance Criteria. Add Background only when extra context is needed.

Non-Goals quality rule: list only things a reader could reasonably infer are in scope after reading Goals, but are actually excluded. Test: "would a reasonable engineer assume this is included?" — if yes, state it is out of scope. Omit anything with no logical connection to the goals, regardless of how it came up: casual conversation mentions, reference-doc features dismissed as unneeded, or "we won't do X" rejections that no one would have inferred were in scope.

Default-prohibited sections — add only when trigger is met:

| Section | Trigger | |---|---| | Compatibility & Sunset | Breaking change or staged migration (see Lifecycle Contract for required TEMPxx details) | | Operational Considerations | 2+ teams impacted, or monitoring/rollout changes required | | root-sub decomposition | Meets Decomposition Strategy Contract conditions | | Risk Classification | Design is non-greenfield, or greenfield touching Critical domains (auth, billing, access control, encryption, PII) |

Verification Plan, Alternatives Considered, and Risks & Mitigations are optional — include when they add value; omit otherwise.

Size guideline (non-blocking): Target 600–1500 words, up to 2 diagrams. If exceeded, before continuing: (1) state in one line why the additional length is necessary, (2) re-evaluate single vs root-sub split.

Quality is judged by Acceptance Criteria clarity, trade-off coverage, and verifiability — not word count. Avoid cargo-cult overhead (release signoff checklists, committee-style gates, extensive ops runbooks) unless requested.

Process

Phase 1: Context Exploration

Before writing anything, understand the landscape:

1. Explore the project structure, existing code, and related documentation
2. Check for existing design docs in docs/plans/<topic>/
3. Check for existing ADRs in docs/adr/<topic>/ — use a tiered reading strategy:
   • Always: List filenames only first (ls docs/adr/<topic>/ 2>/dev/null) to get an overview
   • Then: Read only ADRs that are clearly relevant to the current design topic (judge by title)
   • Never: Read all ADRs upfront — in large projects this will consume context for no benefit
   • If unsure whether an ADR is relevant, read just its Title and Status lines before committing to the full content
4. Identify related components, APIs, or systems that the design will interact with
5. Create a TodoWrite checklist to track the design process phases
6. Determine whether the request includes a breaking change or staged migration; if yes, enumerate candidate temporary mechanisms as TEMPxx and choose lifecycle record mode (ADR or in-doc ledger).
7. Determine decomposition strategy (single or root-sub) using the Decomposition Strategy Contract, and draft the ### Boundary Inventory that justifies the choice.
8. Build a preliminary Constraint Register from existing code/tests:
   • Read affected implementation files and nearest existing tests.
   • Record implicit contracts (data shape, helper behavior, path assumptions, legacy compatibility assumptions).
   • Record likely ripple zones that are not directly requested but may require planned verification.

Phase 1.5: Clarification Gate (Required)

Before drafting the design, remove requirement ambiguity explicitly.

1. Build a clarification list from user requests, existing docs, and code context.
2. Resolve clarification items with the user:
   • If AskUserQuestionTool is available: batch independent items into the questions array (up to 4); ask dependent/blocking decisions in a separate call.
   • If AskUserQuestionTool is unavailable (e.g., Claude.ai): ask multiple independent questions in a single message using QID labels (Q1, Q2, ...); require response format QID: <answer> and allow QID: OTHER(<concise detail>) when no option fits.
   • In either case, include in each question: (1) what decision this resolves, (2) which section of the design doc or artifact the answer will affect.
   • Prefer multiple-choice options when feasible.
3. Classify each clarification item as one of:
   • resolved (explicit answer exists)
   • assumed (no answer yet, but safe temporary assumption documented; requires finalization trigger)
   • blocked (cannot continue without answer)
4. Do not start design drafting while any blocked item remains.
5. For breaking-change designs, treat missing TEMPxx checklist row or missing retirement trigger/verification/removal scope for any TEMPxx as blocked.
6. For non-greenfield changes, treat unresolved high-impact constraints (existing test/runtime assumptions that can change scope) as blocked.
   • If ## Risk Classification is empty or missing for a non-greenfield design, add it as a clarification item (blocked until the user defines risk tiers).
   • If the design is greenfield but touches Critical domains (auth, billing, access control, encryption, PII), treat missing ## Risk Classification as blocked.
7. Record outcomes in the design doc under ## Clarifications with:
   • Question
   • Answer or assumption
   • Finalization trigger (for assumed: what condition or event will convert this to resolved)
   • Impact on scope/design
   • Status (resolved or assumed)

Phase 2: Initial Design Draft

1. Create the initial design doc draft
   • Start with the Core Profile sections; add optional sections only when triggered.
   • Populate ## Decomposition Strategy with Decision Basis grounded in ### Boundary Inventory signals, and keep boundary naming consistent across root/sub artifacts.
   • If non-greenfield, include ## Existing Codebase Constraints and map constraints to design choices.
   • Encode replacement/removal/fail-closed intent as explicit design requirements and acceptance criteria, not prose-only goals.
   • When writing Acceptance Criteria, consult ears-types.md for EARS type definitions and selection guidance. Choose the most specific EARS type; avoid defaulting to Ubiquitous.
   • Classify each AC by Contract Type: schema (data shape validation), api-contract (API interface compliance), cli-contract (CLI behavior compliance), behavioral (logic/state behavior), none (no specific contract). Default to behavioral when uncertain.
   • When the design spans multiple components or has cross-component data flows, distinguish acceptance criteria by level:
     • Component-level AC: each component's individual behavior in isolation.
     • Integration-level AC: observable behavior when components are combined (e.g., end-to-end data flow, API contract, lifecycle correctness across boundaries).
     • Include at least one integration-level AC in this case; component-level ACs alone are insufficient to verify the design.
2. Write to: docs/plans/<topic>/design.md
   • Create the directory if it does not exist: mkdir -p docs/plans/<topic>
3. If Split Decision: root-sub, also create sub docs at:
   • docs/plans/<topic>/<subtopic>-design.md
   • Use the sub-doc template: design-templates.md
4. Present the draft to the user and request feedback

Phase 3: Feedback Loop (Core Loop)

Repeat until the user explicitly approves the design:

1. User provides feedback
2. Update the design doc to address the feedback
3. If a design decision was made during this iteration:
   • Create or update an ADR (see Phase 4)
   • Add a link to the ADR in the design doc's Decision Log section
4. Present the updated design doc and request review

Key behaviors in this loop:

• Do not assume approval from vague responses. Ask explicitly: "Is this design approved?"
• If the user raises a concern, address it before moving on
• If multiple alternatives are discussed, capture the chosen one in an ADR

Phase 4: ADR Management

When a significant design decision is made, record it as an ADR.

Output path: docs/adr/<topic>/<subject>.md

Path rules:

• Create the directory if missing: mkdir -p docs/adr/<topic>
• Use a concise, verb-led kebab-case subject filename (example: adopt-grpc-for-public-api.md)

ADR format: See design-templates.md.

ADR quality bar (derived from proven ADR templates/examples):

• One ADR must capture exactly one decision.
• Include top metadata: Status, Date, and Deciders (if known).
• Write Context and Problem Statement with concrete forces, constraints, and requirement links.
• If trade-offs exist, include Decision Drivers and Considered Options (at least two unless truly single-option).
• Use Decision Outcome to name the chosen option and explain why it wins.
• In Consequences, capture positive/negative/neutral impacts plus concrete follow-up work.
• Add Validation to describe how success is measured (metric/test/review checkpoint).
• Add Links to related ADRs, tickets, PRs, and docs.
• If an ADR defines a temporary mechanism (TEMPxx), include a Sunset Clause (TEMP ID, retirement trigger, retirement verification, removal scope).

ADR lifecycle rules:

• Treat ADRs as immutable history: do not rewrite accepted decisions to fit new reality.
• When a decision changes, create a new ADR and connect it using Supersedes / Superseded by.
• Keep status transitions explicit (Proposed -> Accepted -> Deprecated/Superseded/Rejected).

When to create an ADR:

• Technology or library selection
• Architectural pattern choice (e.g., monolith vs microservices)
• API design decisions
• Data model decisions
• Trade-offs between competing requirements
• Deviations from established project conventions

When NOT to create an ADR:

• Trivial implementation details
• Decisions that are obvious given the project context
• Formatting or style choices already covered by project conventions

Phase 5: Finalization

1. Save the final version of the design doc
2. Verify all design decisions have corresponding ADRs
3. Verify the Decision Log section in the design doc links to all related ADRs
4. For breaking-change designs, verify every TEMPxx has:
   • a Temporary Mechanism Index entry,
   • a lifecycle record (ADR or in-doc ledger), and
   • a Sunset Closure Checklist row with retirement trigger, retirement verification, and removal scope.
5. Verify ## Decomposition Strategy is complete and consistent with produced design files:
   • ### Boundary Inventory exists and uses the required fixed columns.
   • If Split Decision: root-sub, verify:
     • Every boundary-owned ### Boundary Inventory row appears exactly once in Sub-Doc Index Owned Boundary, and vice versa.
     • Every Sub-Doc Index file path exists.
     • Every Root Coverage entry references a valid sub ID or Integration.
     • Every sub ID referenced in Root Coverage exists in Sub-Doc Index.
     • Boundary ownership text is explicit and non-overlapping.
   • If Split Decision: single, verify no unnecessary root/sub scaffolding remains.
   • Run skit split-check <design-file> before finalizing. If it reports FAIL, mark the design as BLOCKED; if it reports advisories, tighten Decision Basis or boundary ownership before approval.
   • Run skit temp-lifecycle-check <design-file>. If it reports FAIL, mark the design as BLOCKED.
6. Verify each ADR meets the quality bar (metadata, context/problem, decision outcome, consequences, validation, links).
7. Verify supersession links are coherent (Supersedes/Superseded by are reciprocal where applicable).
8. Ambiguity Check (Required):
   • Scan all Acceptance Criteria for expressions whose verification cannot produce a deterministic PASS/FAIL result without subjective interpretation. Look for qualitative judgments, undefined thresholds, relative terms, and vague verbs — regardless of language.
   • Common examples (not exhaustive): appropriate, reasonable, adequate, sufficient, timely, properly, correctly, as needed, if possible, 適切な, 十分な, 適宜, 必要に応じて, 正しく, それなりの, しかるべき.
   • If any ambiguous expression is found and has NOT been replaced with a concrete, measurable expression, mark the design as BLOCKED and request the user to revise the AC before approval.
   • If the ambiguous expression has been explicitly replaced with an objectively measurable criterion in the same AC, it is permitted.
9. Goal-AC Coverage Check (Required): For each item in the Goals section, verify that at least one ACxx in Acceptance Criteria has a Requirement Sentence that validates the realization of that goal. If any goal has zero AC coverage, mark the design as BLOCKED and request the user to add missing ACs.
10. Verification Command Check (Required): Run skit verification-cmd-check <design-file>.
    • SKIP: no AC table found — proceed.
    • PASS (with advisories): all commands valid; TBD-at-plan entries are advisory — decompose-plan resolves them.
    • FAIL: one or more ACs have an empty or unresolvable command — mark as BLOCKED and fix before approval.
11. Suggest running design-doc review (independent sub-agent verification) before proceeding to the decompose-plan skill
12. For non-greenfield designs, verify:
    • Every high-impact constraint has at least one linked requirement or acceptance criterion.
    • Every replacement/removal/fail-closed intent has explicit prohibited-path and allowed-path acceptance wording.
    • Verification guidance covers both newly added behavior and impacted existing behavior.
13. For designs spanning multiple components, verify at least one integration-level acceptance criterion exists that can only be verified by exercising multiple components together (not by mocking one side).
14. If the design is non-greenfield OR greenfield touching Critical domains (auth, billing, access control, encryption, PII):
    • Run skit risk-format-check <design-file>.
      • SKIP: no Risk Classification section — only acceptable for greenfield without Critical domains; otherwise mark as BLOCKED.
      • FAIL: format violations found — mark as BLOCKED and fix.
    • Then verify semantically: any Standard entry with generic or circular justification must be escalated to Sensitive or higher.

Design Doc Template

See design-templates.md for the full template. Adapt sections as needed — not every section is required for every design.