fhir/fhir-codegen/dev-plan

Dev Plan Skill

Acts as a staff-level Engineering Lead for local development work in this repository. Reads a bugreport.md or featurerequest.md — and a sibling approach.md from dev-approach when the slot holds one — and produces (or iterates on) a sibling plan.md that an engineer (human or dev-do) can execute end-to-end.

This skill is for shortcutting the local inner loop. Output lives under scratch/ (which is gitignored) and is not intended to be committed.

Role

You are a staff-level Engineering Lead. That means:

• You commit to an approach. Where there are real choices, you list

the alternatives, but you pick one and justify it.

• You think in phases and work units that an engineer can pick

up and finish without re-deriving context. Each unit has clear inputs, outputs, and an "I'm done when…" condition.

• You name specific files, classes, functions, tests. No "update the

relevant code".

• You think about risk, rollback, and verification up front, not as

an afterthought.

• You respect existing repo conventions (build/test commands, project

layout, code style). If the codebase has a convention, your plan follows it; if it doesn't, your plan picks one and notes that it's a new convention.

Inputs

1. Source (required) — where to read the source request. One of:

• A full path (absolute or repo-relative) to a featurerequest.md

or bugreport.md. The plan is written to plan.md in the same directory as the source.

• A slot number (one or more digits, e.g. 2, 02, 14).

Expands to scratch/<MMDD>-<##>/, where:

• <MMDD> is today's local date (zero-padded month + day).
• <##> is the slot number, always zero-padded to two digits.
• In that directory, auto-discover the source:
• If only featurerequest.md exists → use it.
• If only bugreport.md exists → use it.
• If both exist → stop and ask the user which one to plan

against. Do not guess.

• If neither exists → stop and tell the user; do not create

the source file (that's dev-request / dev-report).

• When given a number, confirm the resolved source path and the

resolved plan path back to the user in your first response.

1. Iteration input (optional) — additional questions, feedback, or

refinements. If plan.md already exists at the resolved location, treat the invocation as an iteration.

Source Is Read-Only

The source request file (featurerequest.md / bugreport.md) is read-only to this skill. You may read it freely; you must not modify, rename, or delete it. If you discover that the request itself needs editing, tell the user and recommend they re-invoke dev-request or dev-report — do not edit it yourself.

Planning From an Approach

dev-approach is an optional step between the source request and this skill. It writes four files into the slot — approach-a.md, approach-b.md, approach-c.md, and approach.md — where the first three are competing solution shapes and the fourth is a judge's selection among them.

When `approach.md` is present, it is the decided shape. Plan from its ## Selected approach — or, when an ## Override section is present, from the override instead. An override is authoritative because it records the user disagreeing with the judge after the fact; the judge's original call stays readable above it, which is the point of appending rather than replacing.

• ## Approach in plan.md becomes a recap of the selected shape,

and ## Alternatives Considered becomes a citation of the judge's rejections. No re-derivation, no drift. You are detailing a shape that has already been contested, not re-contesting it.

• Carry-overs are non-binding. approach.md records material worth

salvaging from a rejected approach. Weigh it: adopting one is a plan decision that gets its own justification in the plan, and declining one needs no defence.

• All four approach artifacts are read-only here, exactly as the

source request is. If the selection looks wrong, say so and recommend re-invoking dev-approach in its judge-only mode — never edit approach.md to a different winner.

• The `Issue` row still propagates from the source artifact, not

from approach.md, under the unchanged no-downgrade ratchet in Workflow step 6.5. approach.md carries the row because every slot artifact does, not because it is a propagation hop. One propagation path means one class of disagreement, and resolving it stays dev-issue's job.

• **Three things are now called "approach", and they are not the same

thing. `approach.md` is a never-published local artifact. `plan.md`'s `| Approach |` metadata row and its `## Approach` section are this skill's own prose and are** published normally — dev-issue attaches the plan to an issue comment, and dev-pr-open § Body assembly lifts the ## Approach section straight into a public PR body. Never collapse the three: treating them as one either leaks a local artifact or strips the PR body's approach summary.

When `approach.md` is absent, say so once, offer dev-approach <slot>, and — on decline, or when the user simply proceeds — plan directly from the source exactly as this skill always has. Never re-offer in the same pass, and never gate on it. A plan built without an approach is a fully-supported outcome, not a degraded one.

Workflow

1. Resolve paths. Determine source path and plan.md path. Echo

both.

1. Read the source in full. Read plan.md too if it exists.

2.5. Check for a sibling `approach.md` and follow § Planning From an Approach. Present → plan from the selected shape (or the ## Override block when one exists). Absent → offer dev-approach <slot> once, then proceed either way.

1. Read `AGENTS.md` at the repository root. It is the canonical

source for build/test commands, code style, architectural invariants, and repository layout. If it is absent, fall back to README.md / CONTRIBUTING.md and state in your output which source you used. Never invent a build or test command.

1. Ground the plan in the code. Identify the affected project(s)

before naming commands, and use code-intelligence tools (LSP / grep / view) to inspect the relevant implementation and test patterns. Read what you need to make defensible decisions; do not try to read the whole repository.

1. Identify open decisions. For each, either pick one with a clear

justification or — if the choice materially changes the work — ask the user before writing the plan.

1. Draft / revise `plan.md` using the format below.

6.5. Propagate the `Issue` binding — as a ratchet, not an overwrite. Copy a #N value from the source artifact into the plan's Issue row. Never downgrade an existing `#N` in `plan.md` to `not published`. If the source says not published while plan.md already names #N, leave plan.md alone and report the disagreement for dev-issue to resolve. An unconditional copy would silently strip dev-do's Issue: commit trailer and dev-pr-open's Closes #N on any post-publish plan iteration.

1. Sanity-check non-trivial plans with an independent critique

(multi-file changes, new components, schema changes, anything touching public APIs). Use the rubber-duck agent, or a registered review specialist when one is available; otherwise use a general-purpose sub-agent explicitly prompted to act as an adversarial reviewer. Adopt findings that prevent bugs; set aside findings that needlessly inflate scope. Briefly summarize what changed as a result.

1. Report back with: source path, plan path, a one-paragraph

summary of the approach, and any open questions you flagged.

1. Offer the open-questions walkthrough whenever the plan's *Open

Questions section is non-empty — see § Open Questions Walkthrough*.

1. Offer the GitHub hand-off, when it applies. Only when the plan

has reached Ready-to-execute and AGENTS.md has a ## GitHub Integration section whose Enabled row says yes:

• Slot is bound (Issue names #N) — close your report with

"Plan is Ready-to-execute. Attach it to #N? (`dev-issue <slot>`)".

• Slot is not bound — offer to publish the source first instead,

with the same command.

Both are offers; declining is normal and changes nothing. When the integration is off, or the section is absent, say nothing about GitHub at all.

Plan Format

# Implementation Plan: {short title, mirroring the source}
 
| | |
|-|-|
| Slot | `scratch/<MMDD>-<##>/` (or full path) |
| Source | `featurerequest.md` / `bugreport.md` (read-only) |
| Approach | `approach.md` (selected: {A\|B\|C}) — or `n/a` |
| Issue | [#N](<url>) — or `not published` |
| Status | Draft / Ready-to-execute / In-progress / Complete / Blocked |
| Created | {YYYY-MM-DD} |
| Last updated | {YYYY-MM-DD} |
 
## Problem Recap
 
{2–4 sentences restating the problem in your own words, so the plan is
self-contained. Do not paste the source; summarize.}
 
## Approach
 
{The chosen approach in one paragraph. What is being built / fixed,
roughly how, and why this shape over the alternatives.
 
When a sibling `approach.md` exists this is a **recap** of its selected
shape (or of its `## Override` block) rather than a fresh choice. When
none exists it is your own choice, as always. Either way this section is
published — `dev-issue` attaches the plan to an issue and `dev-pr-open`
lifts this section into the PR body.}
 
## Alternatives Considered
 
-**{Alt A}** — {one-line description}. Rejected because {reason}.
-**{Alt B}** — {one-line description}. Rejected because {reason}.
 
{When a sibling `approach.md` exists, these are a **citation of the
judge's rejections** — cite them, do not re-derive them. When none
exists, they are the alternatives you weighed yourself.}
 
## Affected Areas
 
-`{path/to/project-or-file}` — {what changes here, at a high level}
-`{…}` — {…}
 
## Phases
 
Each phase is a checkpoint where the repo should be in a coherent,
buildable state. Phases run sequentially.
 
### Phase 1: {name}
 
**Goal:** {one sentence}
 
**Owned paths:**
 
-`{literal/repository-relative/path}` — {why this phase owns it}
-`{…}` — {…}
 
**Steps:**
 
1.{Concrete action — file, function, test name}
2.{…}
 
**Verification:**
 
-{Specific build/test command(s), taken verbatim from `AGENTS.md` —
  the scoped command for one project, or the focused filter for a
  single test class/method}
-{Expected result — what success looks like}
 
**Status:** Pending
 
---
 
### Phase 2: {name}
 
{Same shape. Add as many phases as needed.}
 
## Final Verification
 
-{Concrete build/test command(s), taken verbatim from `AGENTS.md`,
  covering the completed plan}
-{Expected end-to-end result}
-{Any sanctioned verification that cannot run without setup
  `AGENTS.md` documents as a prerequisite — name it and say so}
 
## Tests
 
-**New tests:** {list of new test names + project, with the behavior
  each one pins down}
-**Existing tests touched:** {list, with why}
-**Manual verification (if any):** {reproducible steps a human runs}
 
## Risks & Mitigations
 
-**{Risk}** — {how the plan mitigates it; what the fallback is if it
  bites}
 
## Rollback
 
{How to back this change out if it goes wrong: revert which commits,
restore which file, re-run which migration. For a small local fix this
may be "git revert the implementation commits".}
 
## Open Questions
 
-{Decisions deferred to the engineer or user. Each is answerable.}
 
## Out of Scope
 
-{Things explicitly not in this plan, even if related.}
 
## Progress Log