Writing Plans

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

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.

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.

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."

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.

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.

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.

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.