| name | writing-plans |
| description | Guides the creation and structuring of project plans in docs/plans/. Use when writing feature-parity plans, gap analyses, documentation plans, or implementation roadmaps. Covers plan templates, status tracking conventions, phase numbering, task tables, and test plan sections. |
Writing Plans
Create well-structured project plans in docs/plans/ that track feature gaps, implementation phases, and milestones using the conventions established in this repository.
Essential Principles
<essential_principles>
**Every plan starts with a goal blockquote.**
The first content after the title is a > blockquote stating the plan's goal. This tells readers immediately what the plan aims to achieve and scopes every section that follows. Without it, contributors read the plan without knowing what "done" looks like.
**Use a numbered Table of Contents with anchor links.**
Plans are long documents (500–1200 lines). Without a ToC with anchors, readers scroll blindly. Number every top-level section (## 1. ..., ## 2. ...) and every subsection (### 1.1 ...) and link them from the ToC. This also enables cross-references from other documents.
**Track status with emoji, and always define the legend.**
Use ✅ (implemented), 🔧 (partial), ❌ (missing) for feature-gap tables. Use - [ ] / - [x] for milestone checklists. Always include a "Legend" block before the first table that uses status markers — readers who skip the legend misread 🔧 as "done."
**Implementation phases use `### Phase N: Title (Priority: …)` with a bold goal and task table.**
Unnumbered or unstructured phases cause implementers to miss dependencies and work out of order. Every phase needs: a number, a title, a priority level, a one-line bold goal, and a task table with N.M numbered tasks. This format lets contributors pick up any phase independently.
**Never delete completed phases or sections — use amendments.**
Plans are living documents. Completed phases (✅) stay in the plan as a record. If scope changes, add an "Amendments" section at the end rather than rewriting history. This preserves context for anyone reading the plan later.
**Every PR that implements a plan phase must include `Plan:` and `Phase:` lines in its body.**
When creating a PR that implements one or more phases of a plan in docs/plans/, always add:
Plan: docs/plans/<plan-name>.md
Phase: N
The Plan Phase Continuation workflow reads these lines on merge to automatically delegate the next phase to Copilot. Without them the workflow silently skips the PR and no follow-up phase is triggered. Letter phases (e.g. Phase: C) are also supported.
</essential_principles>
Prerequisites
See setup-environment.md for the shared environment
setup. Install pre-commit hooks before making any commits:
uv sync --all-groups
uv run pre-commit install
When to Use
- Planning a new feature set or feature-parity effort with gap analysis
- Creating a documentation or content plan with milestones
- Organizing an implementation roadmap with phased task breakdowns
- Tracking status across multiple features with emoji-based progress markers
- Structuring a test plan tied to implementation phases
When NOT to Use
- Quick bug fixes — use a GitHub issue with reproduction steps instead
- Single-feature implementation — use a PR description or issue body instead
- Architecture Decision Records — use ADR format (
docs/adr/NNNN-title.md) instead
- Meeting notes or status updates — use GitHub discussions or wiki instead
- Skill documentation — use the
designing-workflow-skills skill instead
Plan Type Selection
What kind of plan are you writing?
│
├─ Tracking features to match another system?
│ └─ Feature-Parity / Gap-Analysis Plan
│ (gap tables + implementation phases + test plan + benchmarks)
│
├─ Planning documentation, content, or guides?
│ └─ Documentation / Content Plan
│ (structure tree + section breakdowns + milestones)
│
└─ Unsure?
└─ Start with the feature-parity template — it's the more complete
structure and sections can be removed if not needed.
Quick Reference: File Naming
| Convention | Example |
|---|
| Location | docs/plans/<name>.md |
| Name format | Kebab-case, descriptive |
| Feature parity | cqlengine-feature-parity.md |
| Documentation | documentation-plan.md |
Quick Reference: Status Legend
Always include this legend before the first table that uses status markers:
Legend:
- ✅ **Implemented** — working today
- 🔧 **Partial** — infrastructure exists but not fully exposed via public API
- ❌ **Missing** — not yet implemented
Quick Reference: Required Sections by Plan Type
| Section | Feature-Parity | Documentation |
|---|
| Goal blockquote | ✅ | ✅ |
| Numbered ToC with anchors | ✅ | ✅ |
| Feature gap analysis tables | ✅ | — |
| Gap summary lists | ✅ | — |
| Documentation structure (file tree) | — | ✅ |
| Section breakdowns with examples | — | ✅ |
| Implementation phases | ✅ | — |
| Test plan (unit + integration) | ✅ | — |
| Performance benchmarks | ✅ (optional) | — |
| Migration guide | ✅ (optional) | — |
| Milestones with checkboxes | — | ✅ |
| Writing style guide | — | ✅ (optional) |
| References | ✅ | ✅ |
Quick Reference: Phase Format
Every implementation phase follows this exact structure:
### Phase N: Title (Priority: High|Medium|Low)
**Goal:** One-line description of what this phase achieves.
| Task | Description |
|---|---|
| N.1 | First task description |
| N.2 | Second task description |
| N.3 | Unit + integration tests |
Rules:
- Tasks use
N.M numbering (phase number . task number)
- The last task in every phase should be testing
- Priority is one of:
High, Medium, Low
- Goal is bold and on its own line after the heading
Quick Reference: Gap Analysis Table
| Feature | Equivalent | Status |
|---|---|---|
| `their_api()` | `our_api()` | ✅ |
| `their_other()` | — | ❌ |
| `their_partial()` | `our_partial()` | 🔧 notes |
After each gap table, include a Gap summary list:
**Gap summary — area name:**
- `feature_a` → proposed implementation approach
- `feature_b` → proposed implementation approach
Quick Reference: Test Plan Table
| Test Case | Phase |
|---|---|
| Description of what the test validates | N |
| Another test case | N |
Group test cases by file (tests/test_types.py, tests/test_cql_builder.py, etc.) and cross-reference each test to the implementation phase it covers.
Writing Style
| Rule | Example |
|---|
| Present tense for status | "working today" not "will work" |
| Imperative for tasks | "Add type annotation markers" not "Type annotation markers should be added" |
| Use emoji only for status markers | ✅🔧❌ in tables, not in prose |
| Keep table cells concise | One line per cell; use gap summary lists for detail |
Horizontal rules (---) between major sections | Separates ToC from content, content from references |
Reference Index
| File | Content |
|---|
| plan-templates.md | Full document templates for both plan types with annotated examples |
| Workflow | Purpose |
|---|
| create-a-plan.md | Step-by-step process for creating a new plan from scratch |
| Plan Phase Continuation | GitHub Actions workflow — automatically delegates the next phase to Copilot when a PR merges a plan file or references one via Plan: docs/plans/<name>.md in the PR body |
Success Criteria
A well-written plan:
Automation: Plan Phase Continuation
When a PR introduces a new plan file or references an existing plan via
Plan: docs/plans/<name>.md in the PR body, the
Plan Phase Continuation workflow
triggers automatically on merge to master and delegates the next incomplete
phase to Copilot CLI.
Phase status markers the automation recognises:
| Marker | Location | Effect |
|---|
✅ in ### Phase N: header | Phase header line | Phase is complete |
All task rows contain ✅ | Task table Status column | Phase is complete |
All checkboxes are - [x] | Milestone/checkbox list | Phase is complete |
PR body convention to link a PR to a plan:
Plan: docs/plans/<plan-name>.md
Phase: N ← optional: the phase number this PR completes
See CONTRIBUTING.md for
details and branch-name fallback convention.
