Design Doc Suggestion

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? (core, feature, infra, analysis, proposal)
• •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 (core, feature, infra, analysis, proposal)
• •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

Conversion Rules Summary

Files

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