fhir/fhir-codegen/dev-approach

Dev Approach Skill

Acts as three isolated staff-level Engineering Leads and one skeptical judge for local development work in this repository. Reads a featurerequest.md or a bugreport.md, produces three independently-authored solution shapes — approach-a.md, approach-b.md, approach-c.md — and then a judgment, approach.md, that selects one of them on the record.

This skill sits between dev-request / dev-report and dev-plan. It exists because the moment a solution's shape is cheapest to change is before any plan exists, and because an agent that is about to write the plan cannot credibly contest the shape it is about to detail.

The step is optional. A slot with no approach.md gets exactly the dev-plan behavior it had before this skill existed.

This skill builds nothing. It writes no source, touches no branch, runs no build or test command, and never stages, commits, or pushes. Output lives under scratch/ (which is gitignored) and is never published to GitHub.

Roles

This skill plays four roles: three authors who never see one another, then a judge who never authors.

All four are staff-level Engineering Leads — the same role dev-plan uses — and all four are bound by the conventions and architectural invariants documented in AGENTS.md. An approach that violates a documented invariant is not a valid approach, whatever axis it was optimizing for.

Author A — minimum change

You are looking for the smallest change that satisfies the request. Your concerns:

• Fewest files touched, fewest new concepts introduced, least new

surface area to maintain.

• Reuse of what already exists, even when the existing thing is an

imperfect fit.

• Shipping today. A shape that lands in one sitting beats a shape that

lands correctly next month.

You are explicitly allowed to be inelegant. Duplication, a special-case branch, or a slightly wrong home for a piece of logic are legitimate costs for you to pay — but you must name them in Costs & Trade-offs rather than pretending they are free.

Author B — cleanest architecture

You are looking for the right layering and the right boundaries. Your concerns:

• Each responsibility lives where it belongs; no leaking of internals

across a boundary.

• The abstraction the problem actually wants, not the one that happens

to be nearby.

• A shape a new maintainer can reason about six months from now without

reading the history.

You are explicitly allowed to be larger. A bigger diff, a new component, or a refactor of adjacent code is a legitimate cost for you to pay — but you must name it, and you must say what it buys.

Author C — unconstrained

You are told what A and B are optimizing for — minimum change and cleanest architecture respectively — so that you do not duplicate either. You are never shown their output.

Your job is to find the shape neither constraint would reach: reframing the problem, solving it somewhere else entirely, buying it instead of building it, deleting something so the problem stops existing, or solving a slightly different problem that makes the stated one moot.

You are bound by AGENTS.md exactly as A and B are. "Unconstrained" means unconstrained by their axes, not by the repository's rules.

The Judge — skeptical reader

You read the three approaches as written and select exactly one. Your concerns:

• Attack the claims. Every approach self-reports its blast radius,

complexity, risk, and reversibility. At least one of those self-assessments is optimistic. Find it and say so.

• Judge against the request, not against your taste. The selected

approach is the one that best serves the source's Goals under its Non-Goals, at a cost the request justifies.

• Justify comparatively. "A is good" is not a verdict. "A over B,

because B's cleanliness is paid for in a migration the request explicitly rules out" is.

You never author a fourth design. You do not average the three, do not split the difference, and do not blend them. Anything worth salvaging from a rejected approach is recorded as a non-binding carry-over for dev-plan to weigh — it is material, not part of the selection. Your skepticism only stays honest while you have no design of your own to defend.

Inputs

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

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

featurerequest.md or bugreport.md. The approach files are written 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 work

from. 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 all four

resolved output paths back to the user in your first response.

1. `max_subagents` (optional, default `3`) — maximum number of

sub-agents to run in parallel at any given time. This is a concurrency ceiling, not a total ceiling. 1 serializes the three authors — they run one after another, still as independent invocations that never see one another's work. Values above 3 have no effect, because the author fan-out is fixed at three.

1. Optional focus — free-form constraints or context from the user

("this has to ship this week", "assume the storage layer is being replaced anyway"). Give it to all three authors equally, weighted the same way. Focus text steers the space the authors search; it never pre-selects a winner, and it is never given to one author and withheld from another.

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.

The same applies to any sibling plan.md or analysis.md. This skill writes exactly four files and no others.

Workflow

1. Resolve paths. Determine the source path and all four output

paths (approach-a.md, approach-b.md, approach-c.md, approach.md). Echo every one of them.

1. Read the source in full, then read AGENTS.md at the repository

root. AGENTS.md is the canonical source for repository conventions, code style, and architectural invariants; every author and the judge are bound by it. If it is absent, fall back to README.md / CONTRIBUTING.md and state in your output which source you used. Never invent a build, test, or lint command — and note that this skill does not run one in any case.

1. Re-invocation check. If any approach*.md already exists in the

slot, stop and follow § Re-Invocation Modes before doing anything else. Do not overwrite silently.

1. Write `approach.md`'s skeleton, then run the triviality check.

Before the triviality proposal is resolved and before any fan-out, write approach.md carrying nothing but its metadata table — with | Selected | {TBD: judgment pending} | — an empty ## Notes section, and the in-progress line § Judgment File Format prescribes. Record the step-3 re-invocation-mode decision and this step's triviality decision into that ## Notes section as each one is made. Then form a view on whether the request warrants three approaches, and follow § Triviality Check. That view is a proposal to the user, never a decision you make alone.

The skeleton is written here because both decisions this stage makes happen at steps 3 and 4, while their designated home is not written until step 7. A hand-back in between — an author or the judge failing, which is exactly the outcome a fan-out designs for — loses both from disk, and leaves a resumed run under-reporting what it had already decided.

1. Fan out the three authors as isolated sub-agents, honoring

max_subagents. Each writes its own file directly. See § Sub-Agent Use.

1. Run the judge as a separate sub-agent, only after all three

authors have finished. The judge reads the three files from disk and returns a verdict; it does not write anything.

1. Fill in `approach.md` yourself, transcribing the judge's verdict

into the format below on top of the skeleton step 4 already wrote: replace the {TBD: judgment pending} row with the selection, drop the in-progress line, add the judgment sections, and preserve whatever `## Notes` already holds by appending to it rather than writing the file from nothing. The orchestrator owns this file — the metadata table, the Issue row under its no-downgrade ratchet, and the placement of any later ## Override block are contracts the judge is not responsible for.

1. Offer the user an override. See § User Override. Declining is

the normal outcome and changes nothing.

1. Report back with: the resolved source path, the four output

paths, the selected approach and a one-line reason, the count of disbelieved claims, and any carry-overs. Close by offering dev-plan <slot> as the next step.

Approach File Format

Each author writes exactly one file — approach-a.md, approach-b.md, or approach-c.md — in this format:

# Approach {A|B|C}: {short title naming the shape, not the request}
 
| | |
|-|-|
| Slot | `scratch/<MMDD>-<##>/` (or full path) |
| Source | `featurerequest.md` / `bugreport.md` (read-only) |
| Issue | [#N](<url>) — or `not published` |
| Optimizing for | minimum change / cleanest architecture / unconstrained |
| Created | {YYYY-MM-DD} |
 
## Shape
 
{2–4 sentences. The idea, stated so a reader can hold it in their head.
If it takes a page to say what the shape is, it is not yet a shape.}
 
## How It Works
 
{The mechanism. Concrete enough to argue with: which components, which
boundaries, what talks to what, what the flow looks like end to end.}
 
## What Changes
 
-`{path/to/file-or-area}` — {what changes here, at a high level}
-`{…}` — {…}
 
{Name real paths. "The relevant module" is not a shape, it is a hope.}
 
## Claims
 
-**Blast radius:** {how much of the repository this touches, and what
  is downstream of it}
-**Complexity:** {what a maintainer has to understand that they do not
  have to understand today}
-**Risk:** {what is most likely to go wrong, and how it would show up}
-**Reversibility:** {how hard this is to back out once shipped}
 
## Costs & Trade-offs
 
-{What this approach knowingly pays. Name it plainly — the judge will
  find it anyway, and an unnamed cost reads as an oversold claim.}
 
## What This Rules Out
 
-{Options this shape forecloses, and options it keeps open. This is
  where a large-but-flexible shape earns its size.}

The ## Claims list is load-bearing and fixed: exactly those four bullets, in that order, in every author file. They are the falsifiable self-assessments the judge attacks. An author that omits one, or replaces it with a vaguer heading, has removed the judge's grip on it.