writing-plans

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

Plan: docs/plans/<plan-name>.md
Phase: N

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

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

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

Reference Index

Success Criteria

A well-written plan:

• Lives in docs/plans/<kebab-case-name>.md
• Starts with a goal blockquote immediately after the title
• Has a numbered Table of Contents with working anchor links
• Includes a status legend before the first status-marked table
• Uses ✅/🔧/❌ consistently in gap tables (feature-parity plans)
• Uses - [ ]/- [x] for milestones (documentation plans)
• Numbers implementation phases as ### Phase N: Title (Priority: …)
• Includes a bold Goal: line under each phase heading
• Numbers tasks as N.M within each phase
• Ends every phase with a testing task
• Cross-references test cases to implementation phases
• Uses --- horizontal rules between major sections
• Has no empty sections or TODOs without context

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:

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.