Creates and manages development documents — proposals, issues, and architectural decision records (ADR). All documents live under `./dev/` grouped by topic subdirectories: `./dev/proposals/{topic}/`, `./dev/issues/{topic}/`, and `./dev/adr/{topic}/`. Use this skill when: suggesting new features or architectural changes, proposing refactoring strategies, documenting design decisions, writing issue reports, creating review responses or iterations, or discussing complex implementation approaches. Triggers: "write a proposal", "create an ADR", "document the design", "file an issue", "write up the problem", "review response", "document the analysis/findings".
Create and manage development documentation: proposals, issues, and architectural decision records (ADR).
All three categories use topic subdirectories. Documents are numbered per-topic.
dev/
├── proposals/{topic}/ # Design proposals grouped by topic
│ └── caching/
│ ├── 01. RESPONSE_CACHING.md
│ └── 02. RESPONSE_CACHING_REVIEW.md
├── issues/{topic}/ # Bug reports and improvements grouped by topic
│ └── performance/
│ └── 01. SLOW_QUERY_ON_LARGE_DATASETS.md
└── adr/{topic}/ # Architectural decisions grouped by topic
├── authentication/
│ └── token_refresh/
│ ├── 00. TOKEN_REFRESH_STRATEGY.md ← task / problem statement
│ └── 01. TOKEN_REFRESH_STRATEGY.md ← analysis & proposal
├── logging/
│ └── structured_logging/
└── configuration/
└── environment/
| Category | Path pattern |
|---|
| Numbering scope |
|---|
| Proposals | ./dev/proposals/{topic}/XX. NAME.md | Per-topic directory |
| Issues | ./dev/issues/{topic}/XX. NAME.md | Per-topic directory |
| ADRs | ./dev/adr/{topic}/XX. NAME.md | Per-topic directory |
00. files are task/problem definitions — short documents outlining what needs to be researched or solved.01+ files are the analysis, proposal, or decision documents produced by the task.lowercase_with_underscores. May be nested (e.g., authentication/token_refresh/).XX. SHORT_DESCRIPTION.md
XX — two-digit incremental number (00, 01, 02, …)SHORT_DESCRIPTION — UPPERCASE English words separated by underscoreslowercase_with_underscores✅ GOOD:
dev/proposals/caching/01. RESPONSE_CACHING.md
dev/proposals/caching/02. RESPONSE_CACHING_REVIEW.md
dev/issues/performance/01. SLOW_QUERY_ON_LARGE_DATASETS.md
dev/adr/authentication/token_refresh/00. TOKEN_REFRESH_STRATEGY.md
❌ BAD:
dev/proposals/01. RESPONSE_CACHING.md (missing topic dir)
dev/issues/Performance/01. bug.md (uppercase dir, lowercase title)
dev/adr/AUTHENTICATION/01. STRATEGY.md (uppercase dir)
Always URL-encode spaces as %20 in Markdown links.
✅ [01. STATUS_IMPLEMENTATION.md](01.%20STATUS_IMPLEMENTATION.md)
❌ [01. STATUS_IMPLEMENTATION.md](01. STATUS_IMPLEMENTATION.md) ← unencoded space
Cross-category links use relative paths from the linking file:
Related ADR: [01. TOKEN_REFRESH_STRATEGY.md](../../adr/authentication/token_refresh/01.%20TOKEN_REFRESH_STRATEGY.md)
Related issue: [01. SLOW_QUERY_ON_LARGE_DATASETS.md](../../issues/performance/01.%20SLOW_QUERY_ON_LARGE_DATASETS.md)
Every document MUST start with YAML frontmatter (the
---delimited block).
# [Topic Title]
Brief description of what needs to be researched or solved.
## Current State
Summary of the current situation or observed problem.
## Tasks
- [ ] Research / analyse the current implementation
- [ ] Identify root causes or improvement opportunities
- [ ] Write detailed analysis and proposal in a separate document
### Output
- Proposal: [01. TOPIC_NAME.md](01.%20TOPIC_NAME.md)
---