dvduongth/design-doc

Design Doc Skill

Intent Layer

Role

• Owner role: Designer
• Primary agent: Designer Agent (Design Doc)
• Depends on: design-ingest outputs
• Handoff: outputs → design-validate

Goal

Generate a feature-scoped Design Doc from an ingest package using templates/design-doc-template.md.

Use when

Use this after /design_ingest has produced:

• ingest-summary.md
• source-manifest.md

Constraints / Requirements

This skill is Decision-making only. Your job is to read the ingest package and make design decisions — NOT to validate them. Do NOT self-validate. Do NOT run a quality checklist against your own output. design_validate will catch issues independently.

Anti-patterns

Quality standard

Output format

Output language: Vietnamese but keep session, keywords in English

Invocation parameters

• feature_id (required): NNN-slug
• ingest_run (optional): run folder name or latest

---

Knowledge Layer

Required reading

• templates/design-doc-template.md
• docs/runs/<feature_id>/<ingest_run>/ingest-summary.md
• docs/runs/<feature_id>/<ingest_run>/source-manifest.md
• If exists: docs/runs/<feature_id>/<ingest_run>/requirement-brief.md (generated by design-ingest --brief)
• templates/template-map.md — read the YAML block to determine applicable templates and references

Domain knowledge

Mechanic & Rule fidelity (CRITICAL — no lossy compression)

When writing mechanics, rules, or any behavioral description from source documents, use this format:

WHAT (always required) + HOW, WHEN, WHY, WHO (required if present in source — never drop)

| Field | Question answered | Example | |---|---|---| | WHAT | What does this mechanic/rule do? | "[Entity A] is sent to [destination]" | | HOW | How exactly does it work? Algorithm, direction, method | "nearest = closest in [direction] measured from [reference point]" | | WHEN | Precise timing or trigger condition | "immediately after [triggering action] completes" | | WHY | Design intent or rationale | "[design intent — e.g., punishment / reward / catch-up mechanism]" | | WHO | Which entity the rule applies to | "only [affected entity] — [other entity] is unaffected" |

Related skills / prior steps

• Prior: design-ingest
• Next: design-validate

Key constraints

Rule: If the source describes HOW/WHEN/WHY/WHO → it must appear in the design-doc. Never compress to outcome-only.

---

Execution Layer

Pre-flight (run before reasoning)

1. python tools/scaffold_run.py <feature_id> doc Creates the run folder + input.md. Note the printed path.
2. Detect is_game_feature:
   • Check requirement-brief.md "Affected systems" for: Economy, Progression, Matchmaking, Social
   • Or check ingest-summary.md for game mechanics vocabulary: "turn", "round", "player action", "win condition", "score", "level", "session", "mechanic", "rule", "board". Do NOT use specific game product names as detection signals.
   • If uncertain: use AskUserQuestion "This looks like a game feature — populate game sections (§5 Flow/Steps, §7.5 Economy)? [yes/no]"
3. If is_game_feature = true: also create docs/design-docs/<feature_id>/manifest.md using the Design Package Status template from templates/template-map.md

Writing the Design Doc

1. Populate sections using Facts first (from ingest-summary)
2. Any content not directly supported by sources must be:
   • tagged as an Assumption, OR
   • moved into Open Questions

Diagrams

When a section describes a flow, process, or set of relationships with ≥4 steps or states, invoke skill mermaid-diagram to create diagram.

Where to save:

• docs/assets/design/<feature_id>_<what_it_shows>.md

Where to place the link in the doc: Place the diagram link inline, directly below the section/paragraph it illustrates.

Do NOT create a standalone ## Diagrams section. Each diagram belongs next to the content it describes. Examples:

• Core loop steps → link goes right after the last step of Core loop
• Combo detection rules → link goes right after the last combo rule in the Rules table
• Board structure concepts → link goes right after the Relationships section in Glossary

Format:

> **[Diagram title]** — [filename.md](relative/path/to/filename.md)
> One sentence describing what it shows.

Acceptance statements mapping

If ingest has an AC-seeds or "Signals for design_doc":

• Reference or create acceptance statements in the AC Mapping section (§9)

If nothing exists yet:

• Add a lightweight "Acceptance statements" list (convertible to AC by design_promote)

Expected output

Output locations (MUST follow)

Canonical Design Doc: Write: docs/design-docs/<feature_id>/design-doc.md

Run artifacts (append-only): Create: docs/runs/<feature_id>/<YYYYMMDD_HHMM>_step1_design/

Write:

• input.md — feature_id, ingest run used, template path
• notes.md — key decisions made, open questions deferred, next step

notes.md content requirements

• Template used: templates/design-doc-template.md
• is_game_feature detected: true/false (and basis for detection)
• Key design decisions made (not deferred)
• Assumptions introduced in the doc
• Open questions still unresolved (will be caught by validate)
• If is_game_feature = true:
  • "Also create docs/design-docs/<feature_id>/layout-detail.md using templates/layout-detail-template.md — link it from §6 Visual Design."
  • "Update manifest.md Status for design-doc.md to draft."
• Suggested next step:
  • If is_game_feature: "/design_validate <feature_id> — also complete layout-detail.md before validate for full coverage."
  • Otherwise: /design_validate <feature_id>

---