new-design-doc

This skill helps identify when a design document should be created and guides the process.

Prerequisites

Before triggering, check that the project has been set up with the backlog system.

Look for either:

• backlog.org in the project root, OR
• docs/design/ directory exists

If neither exists, do NOT proactively trigger this skill. The project hasn't been set up with the backlog system yet. Silently skip - don't suggest setup or explain why the skill isn't running.

Exception: If the user explicitly asks to "create a design doc" or similar, you may suggest running /backlog:setup first to initialize the system.

When to Offer This

Trigger conditions for NEW design doc:

• Discussion involves significant architectural decisions
• Multiple approaches are being weighed with tradeoffs
• User mentions "RFC", "RFD", "design doc", "proposal"
• User says "we should document this", "let me think through..."
• A feature requires coordination across multiple components
• Changes that will affect how others use the system

Trigger conditions for CONVERTING existing markdown:

• User mentions "convert to org", "migrate to org-mode"
• User has markdown design docs in docs/legacy/ or similar
• User asks about integrating old documentation
• Discussion references existing .md design documents
• User says "we have an old RFC", "there's a markdown doc for this"

Proactive offers:

For new doc: "This seems like a significant design decision. Should I create a design doc to capture the motivation, options, and decision? That would help track the rationale and any implementation tasks."

For conversion: "I see there's an existing markdown document for this. Should I convert it to org-mode format? I can extract the tasks, assign IDs, and optionally queue them to the backlog."

Workflow

1. Confirm Scope

Ask:

• What's the one-sentence summary?
• What category? (read valid categories from README.org's * Document Categories table)
• Any specific options already being considered?
• (If converting) Which markdown file should I convert?

2. Create the Document

For new docs: Use /new-design-doc <title> to scaffold, then:

1. Fill in Summary - one paragraph overview
2. Fill in Motivation - why this matters, what problem it solves
3. Fill in Design - options considered with tradeoffs
4. Add Tasks - implementation work with [PROJECT-NNN-XX] IDs
5. Add Questions - open issues as ** OPEN

For conversion: Use /new-design-doc <title> <source.md> to convert, then:

1. Review the converted structure
2. Verify task IDs are properly assigned
3. Check that code blocks converted correctly
4. Offer to queue tasks to backlog

3. Use Org-Mode Properly

Remind yourself:

• Documents are numbered sequentially (001, 002, ...) - check existing docs for next number
• Add #+CATEGORY: to frontmatter (use categories from README.org)
• Use ** TODO [PROJECT-NNN-XX] Task title (not markdown checkboxes)
• Use ** OPEN Question / ** DECIDED Question (not plain text)
• Add :PROPERTIES: for EFFORT, VERSION, DECIDED date
• Reference the template: docs/design/000-template.org

4. Update Index

Add the new doc to docs/design/README.org in the appropriate section.

5. Queue Tasks (for conversions)

After converting, offer to queue extracted tasks:

• List tasks with their new IDs
• Ask which to queue to backlog Active section
• Use /task-queue for each selected task

What Makes a Good Design Doc

| Section | Good | Bad | |------------|-------------------------------------------|------------------------| | Summary | "Add caching layer to reduce API latency" | "Caching stuff" | | Motivation | Explains the problem and why it matters | Jumps to solution | | Design | Shows 2-3 options with tradeoffs | Only shows chosen option| | Tasks | Specific, actionable, has IDs | Vague, no IDs |

Conversion Rules Summary

| Markdown | Org-Mode | |----------|----------| | ## Heading | * Heading | | - [ ] Task | ** TODO [PROJECT-NNN-XX] Task | | - [x] Task | ** DONE [PROJECT-NNN-XX] Task | | ```lang | #+begin_src lang | | [text](url) | [[url][text]] |

Files

• Template: docs/design/000-template.org
• Index: docs/design/README.org
• Examples: Any existing docs/design/NNN-*.org