Bootstrapping Design Docs

For the rest of this document {DESIGN_DOC_SKILL_NAME} will refer to the name of the skill we will make that will later be used to generate design docs for this project. Default: creating-design-doc. Once you create the base design doc template and skill, you must ask questions to the user to help clarify anything you are unsure of. This is a joint user-agent process: ask targeted questions when unsure; do not finalize templates without user review.

Note: Templates are bundled with the skill (not in design-docs/) per Agent Skills progressive disclosure pattern.

If the repo has an existing agent config directory, use it. If multiple exist, prefer the current agent's. If none exist, create one.

Before asking questions, scan the repo to ground defaults: If you have not already, run the $activating-memories skill to get an overview of the project.

1. Languages/frameworks/build files
2. CI entrypoints
3. Project Specific Utility modules
4. DB/migrations
5. Style rules

2. Write design doc skill and bundled templates:

   • design-docs/README.md (workflow + approvals)
   • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/SKILL.md (the skill)
   • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md (template index)
   • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/base.md (meta template with guardrails)
   • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/skill.md (skill creation template)
   • .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/feature.md (feature template)

3. Run Adaptive Questioning Protocol:

   • Produce "Detected Defaults Summary"
   • Ask triggered questions
   • Stop for answers before proceeding

4. Idempotency:

   • Never overwrite existing templates without timestamped backup
   • Add new variants to .{AGENT_NAME}/skills/{DESIGN_DOC_SKILL_NAME}/templates/README.md

Stop and ask for [blocking] answers before proceeding.

2. [blocking] Test integrity policy

   • "What is your rule on mocks? (only mock boundaries; prefer record/replay; never mock core transforms)"
   • Why: populates guardrails + testing strategy.

3. [blocking] Data capture constraints

   • "Can we store captured payloads under tests/fixtures/? Any size/licensing/PII constraints?"
   • Why: populates test-data acquisition plan.

4. [blocking] Destructive actions boundary

   • "What DB reset patterns are allowed in tests? (transactions/temp schema/containers). Forbidden actions?"
   • Why: prevents unsafe "delete DB to pass tests" behavior.

5. [important] Type discipline

   • "For Python projects, what is your stance on Optional/None? (forbid unless justified; require invalid states unrepresentable)"
   • Why: shapes interface-contract requirements.

6. [important] Review workflow

   • "Stop at Template Delta Preview for approval, or write files and you review diffs?"
   • Why: controls collaboration checkpoint.

1. Identity and lifecycle
2. Context
3. Problem
4. Goals / Non-goals
5. Requirements (FRs / NFRs)
6. Constraints and invariants (include DB + test integrity)
7. Proposed design (architecture, contracts, schemas, idempotency/retries)
8. Project common utilities that will be used.
9. Project common utilities that will be created.
10. Interface contracts (explicit signatures; Optional/None justification required)
11. Alternatives considered (>=2)
12. Test data acquisition plan (mandatory for external I/O / ETL)
13. Testing and verification strategy (commands + CI gates + test integrity rules)
14. Rollout / migration / ops (flags, backfills, observability, runbook)
15. Open questions / follow-ups
16. Subtasks (human-readable checklist for review)

Subtasks Section Format:

## Subtasks

### T1: [Task Title]
- **Summary**: One sentence objective
- **Scope**: What's in / what's out
- **Acceptance**: Binary pass/fail criteria
- **Status**: [ ] Not started / [~] In progress / [x] Complete

### T2: [Task Title]
...

• Reuse-first rule (anti-duplication): search existing utilities; record decision per task.
• No destructive shortcuts: never delete dev/prod data to pass tests; destructive actions require confirmation.
• Test integrity (anti-mock-cheating): mock boundaries only; prefer record/replay; do not change tests without spec change approval.
• Signature discipline (anti-vagueness): explicit types/invariants; Optional/None requires justification and handling strategy.
• Alternatives requirement: evaluate >=2 alternatives + "do nothing".
• Uncertainty protocol: ask [blocking] questions when unsure; do not proceed.