grepug/plan-driven-change

Plan-Driven Change

Plan-first development cycle for larger changes. Combines brainstorming-style intent review with a tracked plan document and explicit implementation traceability.

If the change creates or reshapes module boundaries, introduces a new nested layer, changes public entrypoints, touches multiple layers where responsibilities may blur, or is happening in a repo with weak or duplicated boundary docs, load module-boundary-governance before finalizing the plan.

When to Use

• New capabilities, features, or modules
• Changes touching 3+ files or involving architectural decisions
• Anything where scope is unclear or risks exist

Skip for: bug fixes, one-liners, dependency bumps, config tweaks, and small maintenance edits. Act directly for those.

Phase 0: Discover Project Conventions

Before starting, quickly orient to the project:

• Use scripts/discover_plan_conventions.py <repo-root> when available to inspect the repo before making assumptions about plan storage or archival.
• Where does the project store active plans or design docs? Check for docs/, docs/plans/, docs/rfcs/, docs/decisions/, .github/, planning/, or similar. If none found, default to docs/plans/.
• Does the repo keep old plans in place, or archive them out of the live plan folder?
• If the repo archives plans, does it use an archive index such as docs/plans/ARCHIVED.md?
• Does the repo use any separate task ledger at all, or is the active plan file the execution tracker?
• What are the build, lint, and test commands? Check package.json, Makefile, README, justfile, pyproject.toml, or CI config.
• What language(s) and conventions does the project use for interfaces and types?
• Does the project already define module boundaries, public entrypoints, or ownership docs? Check for boundary manifests, architecture docs, rules docs, or module readmes.

Use these findings throughout the workflow — don't hardcode assumptions. The skill must follow repo-specific plan retention conventions instead of inventing its own.

Boundary-sensitive changes

Load module-boundary-governance when any of these are true:

• a new module root is being created
• a new nested layer is being introduced
• code is moving across declared layers
• public entrypoints are being added, removed, or widened
• the change touches multiple layers where ownership could become ambiguous
• the repo has weak, prose-only, or duplicated boundary rules that need an adoption audit

Phase 1: Intent Brainstorm (no code, no files yet)

Load the brainstorming skill. Then conduct a focused scoping conversation:

1. Ask one question at a time to clarify:

   • What exactly is being built and why?
   • What is explicitly out of scope?
   • What is the biggest risk or unknown?
   • Are there simpler alternatives worth considering?

2. Challenge assumptions: if a simpler approach exists, surface it before planning the complex one.

3. Once aligned, produce the intent block in chat (not a file yet):

What: <one sentence>
Why: <one sentence>
Out of scope: <one sentence>
Key risk: <one sentence>

4. Wait for user approval of the intent block before moving to Phase 2. Do not proceed without an explicit "go" or equivalent.

The approved intent block becomes the seed for the Context section of the Phase 2 plan document.

Phase 2: Plan Document

Create a plan file at the project's established location (discovered in Phase 0), using a consistent naming scheme. Default if no convention exists:

docs/plans/YYYY-MM-DD-NN-<kebab-topic>.md

NN is a zero-padded two-digit sequence number for that calendar day, starting at 01. List existing files for that date and increment from the highest NN found (or use 01 if none exist).

The plan is a design document first, checklist second. It should be rich enough that any engineer can implement without asking follow-up questions.

Plan retention and archival conventions

• Follow existing repo policy if present.
• If the repo uses a live working set plus an archive index, do not invent a second archive system.
• If the repo has no archival convention and you need to introduce one, default to a live working set plus docs/plans/ARCHIVED.md metadata index with git-based recovery commands.
• Archive indexes are metadata only. Do not copy full archived plans into the index.
• Prefer local git recovery commands over host-specific web URLs.
• Do not ask the user to choose between equivalent archive mechanics when the repo has no policy and the skill already defines the default.
• If the repo has no separate task ledger convention, the active plan file is the default execution tracker.

Example archive-index convention:

• File: docs/plans/ARCHIVED.md
• Concrete example: assets/ARCHIVED.example.md
• Columns:
  • Original plan
  • Archived on
  • Summary
  • Recovery
• Recovery examples:
  • git log --follow -- docs/plans/<filename>.md
  • git show <commit>:docs/plans/<filename>.md

Required sections (always present)

# <Topic>

**Date:** YYYY-MM-DD
**Status:** Draft | Ready for implementation
**Target path:** `path/to/affected/module/`

<!-- Optional: Supersedes: [prior-plan.md](link), Based on: [review.md](link) -->

---

## Context

<2–4 sentences: what problem this solves, why now, and — if this replaces a prior design —
what the old approach got wrong. Be specific. Name the actual file or abstraction being fixed.>

---

## Design

<!-- One ## sub-section per major component. Each section contains:
     - the interface / signature stub (always — even a brief stub in the project's language)
     - rationale: why this shape / approach
     - key design decisions with > **Why X not Y:** callouts for non-obvious choices
     - execution flow in numbered pseudocode if the component has a complex happy-path -->

### <Component Name> (`path/to/file`)

<interface or signature stub — use the project's language conventions, not full implementation>

<rationale paragraph>

> **Why X not Y:** <one-sentence justification for a non-obvious choice>

<!-- Execution flow — include only when the component orchestrates multiple steps -->

**Flow:**

method(input):

1. <step>
2. <step> ...

---

## Boundary  <!-- required for boundary-sensitive changes -->

<!-- Include this section whenever module-boundary-governance applies.
     State the owning manifest, affected layers, whether the manifest changes,
     whether the public surface changes, and the main risk of boundary drift. -->

Owning manifest: `path/to/boundary.manifest.yml`

Affected layers:
- `<layer-id>`

Manifest changes:
- [ ] none
- [ ] add or update layer definitions
- [ ] public surface changed

Boundary risk:
- <main risk of responsibility or dependency drift>

---

## Folder Structure  <!-- include only when new directories or files are being created -->

path/to/module/ ├── file-a — <one-line purpose> └── file-b — <one-line purpose>

<!-- Include a "Why This Layout" comparison table if the structure replaces an existing one -->

---

## Checklist

<!-- Each item names the file(s) it touches and references the design section above.
     Steps are ordered by dependency. Verification steps are explicit, not assumed. -->

- [ ] <step> — `path/to/file` (see §<ComponentName>)
- [ ] <step> — `path/to/other`
- [ ] Verify: build + lint + tests pass

## Tweaks

<!-- appended after implementation -->

Rules for each design section

• Always include an interface/signature stub for every new component — even a 3-line stub is enough; use the project's own language and conventions
• Use > **Why X not Y:** callouts for any decision another engineer might question
• Include execution flow pseudocode when a method coordinates 4+ distinct steps
• Keep rationale paragraphs to 3–5 sentences; link to external docs rather than quoting them

Rules for the checklist

• Each item names the file(s) it touches and cross-references the relevant design section (see §ComponentName)
• Verification steps (build, lint, tests) are explicit items — use the actual commands for the project
• Steps are ordered by dependency — no step assumes earlier unfinished work
• The default execution tracker is the active plan file under ## Checklist
• Only use a separate tracker if the repo explicitly uses one

Review pass before sharing

Do a brainstorm-style review pass on the full document before showing it to the user:

• Is every component in the checklist also covered in the Design section?
• Is there a signature stub for every new file?
• If the change is boundary-sensitive, is there a ## Boundary section with an owning manifest and affected layers?
• If the repo is adopting manifests, does the plan say which old boundary artifacts are kept, superseded, or removed?
• Flag any step that is underspecified or too coarse — propose splits
• Ask: "is there a simpler sequence?"
• Ask: "what's the test strategy for the riskiest step?"

Wait for user approval of the plan. The user may reorder, add, or remove items. Do not begin implementation until they say "go" or equivalent.

Phase 3: Implementation

Work through the checklist top-to-bottom:

• Check off items as completed in the active plan file under ## Checklist
• Only use a separate tracker when the repo explicitly uses one
• Run verification steps (build, lint, tests) at the milestones specified in the checklist
• If a step reveals unexpected complexity, stop and surface it before continuing — do not silently expand scope

Communication and Logging

While implementing, leave a compact trail that makes the work easy to review:

• Before editing, post a short summary of what part of the plan you are starting
• During implementation, send brief phase updates when you complete a meaningful checklist item or discover a risk
• Record verification commands and outcomes explicitly in chat or in the plan file's checklist; do not collapse them into "verified"
• At handoff, summarize:
  • what changed
  • what was intentionally deferred
  • what risks or follow-ups remain

If the project already has a decision log, changelog, ADR folder, or implementation-notes convention, append to that instead of inventing a new logging location.

Guardrails

• If the repo tracks work in docs/plans/*.md, do not introduce tasks/todo.md.
• If the repo archives plans via an index, do not leave stale completed plans in the live folder without reason.
• If the repo keeps historical plans in place, do not invent an archive pass.
• Keep these concerns separate:
  • active plan tracking
  • durable lessons or knowledge capture
  • historical plan archival

Commenting Standard

Write comments for future readers working without full context. That includes teammates, your later self, and AI assistants reading one file at a time. Favor rich local explanation when it helps a future editor understand why the code exists or why it works this way. Do not narrate obvious code.

File header docs

New files and heavily reshaped files should open with a short header comment that explains:

• what the file is responsible for
• why it exists if that is not obvious from the name
• how it fits into the surrounding system
• any non-obvious design choice, dependency, or boundary that matters to future edits

If the file is part of a larger flow, call out the key related module, entrypoint, or owning abstraction so readers know where to look next.

Function and method docs

Document the contract, not the implementation. Add function or method comments when a reader would otherwise miss:

• the purpose of the operation
• important constraints, invariants, or edge cases
• ambiguous return-value behavior
• side effects such as network calls, file writes, cache invalidation, or state mutation

Skip doc comments for trivial getters, obvious helpers, or code whose behavior is already clear from the signature and name.

Inline comments

Use inline comments to explain the why behind a choice:

• why this branch exists
• why a workaround is safe
• why an invariant holds
• why one trade-off was chosen over another

Do not restate what the next line of code obviously does. Good inline comments usually sit next to subtle logic, protocol edges, migrations, compatibility shims, retry behavior, or ordering assumptions.

Architectural and decision comments

When code embodies an important design decision, add a local note that captures the trade-off. Keep broad system rationale in the plan document, but keep enough context in the code so a future editor can safely modify it without hunting through old chat or plan history.

TODO, HACK, and FIXME comments

Make temporary comments actionable and traceable:

• say what needs to change
• say what blocks it or when it can be removed
• include an issue, ticket, bug, or other anchor when one exists

Quality bar

• Prefer plain language over jargon
• Explain why, not what
• Be specific about constraints and behavior
• Reference constants or abstractions by name instead of duplicating values in prose
• If a component needs long comments to be understandable, improve the design, split the component, or strengthen the plan before adding more explanation

Phase 4: Gap Audit

After all checklist items are checked:

1. Re-read the Context section of the plan — does the implementation match what was promised?
2. If module-boundary-governance applied, run the boundary audit and record whether changed files still match the manifest.
3. Scan for missed test coverage, unhandled edge cases, or broken contracts
4. Verify that build, lint, and all tests pass cleanly
5. Confirm the final implementation notes cover verification results, deferred items, and remaining risks
6. Any gaps found become new checklist items and are fixed before done

Phase 5: Tweaks

Post-implementation polish or orphan changes that emerge from conversation:

• Append to the same plan file under ## Tweaks as one-liner checked items:

  - [x] Fixed edge case in parser — added null guard
  

• If no parent plan file exists for the tweak, create a new sequenced plan file for that day with just a ## Tweaks section.
• Default to recording follow-up polish in the active plan file. Only use a separate tracker if the repo explicitly uses one.