Port feature
Port a feature that already works in a REFERENCE implementation into a TARGET stack, in the target's own idiom. Pulls the porting confidence — what the feature does, what the target has, what's missing, what to reuse — onto disk as one gap map at the discover → plan entry, then hands off: a single pass, not a loop and not a pipeline.
Inputs
Infer first from the request and cheap repo evidence (Project Matrix, cwd, CONTEXT.md, ADR names); interview /feature-prompt-style only for what's genuinely missing:
- Feature to port — the behaviour/workflow being brought over.
- REFERENCE PROJECT-CODE — the source of behaviour truth.
- TARGET PROJECT-CODE — where the feature lands.
Do not start discovery until all three are known; if the user is away and one cannot be inferred, stop with a Needs-user note naming exactly which is missing — never guess.
Source-of-truth framing
Carry this through every gap-map section:
- The REFERENCE is truth for behaviour — workflow, navigation (menu placement, entry points, routes), permissions, data effects, and states. When the target's current behaviour disagrees with the reference, the reference wins (unless the user has explicitly decided to change the behaviour — a
/grill-with-docs decision, not one this skill makes).
- The TARGET's design system is truth for UI. When reference UI conflicts with the target design system, choose the design system and record the deviation (reference did X; target DS does Y; chose DS) in the UI/design gaps section.
- Never hardcode stack rules. Read the target's rules from its binding context —
CONTEXT.md, specs/adr/, AGENTS.md — and its UI-coding skill. If a rule the port depends on (stack version, DS convention, component discipline, ADR location) is not recorded there, do not invent it — surface it under Open questions / Needs-user rather than guessing.
Rules
- Suggest, never auto-chain. End by suggesting
/grill-with-docs on the gap map, then stop. Do not run planning, do not open issues, do not implement.
- Never implement here. No product code, config, or migration edits; the only write is the gap map file.
- Name the full PROJECT-CODE from the Project Matrix everywhere; never mix one project's conventions, tokens, or components into another.
- Narrow retrieval only. Trace the reference and survey the target with targeted, evidence-backed search (
rg/git grep for the exact route/path/symbol/state), /feature-discovery-style. Never bulk-read a repo or its specs/ tree to "find everything".
- If
graphify-out/graph.json exists (project root, else workspace root), query it before raw search; older than ~7 days → suggest graphify update .; missing → skip graphify. Verify graph answers against current code.
- Retrieval order.
CONTEXT.md + specs/adr/ are binding (read before deciding) > the current request, reference/target code, and tests > native CLI memory.
- Decisions are artifacts. The output is the durable gap map file, not a chat summary; chat reports only what was written and the phase update.
- Don't fabricate an issue before coding. Issues come later, from
/to-tickets after /grill-with-docs.
- Sub-agents: dispatch local lanes automatically for independent work — never cloud agents; announce the lane count at dispatch and report each lane as it completes.
Process
1. Read the target's binding context
CONTEXT.md and specs/adr/ in the target's <artifacts-root>, plus the target's AGENTS.md and UI-coding skill for stack/DS rules. Done when the binding rules are in hand or each absence is noted for Open questions.
2. Discover the reference
Trace the real behaviour, workflow, navigation, permissions, states, and data effects, /feature-discovery-style. Done when every claim carries a concrete ref (file:symbol, route, migration, test).
3. Survey the target's current state
What exists today, what's partial or wrong versus the reference, and which design-system components and existing patterns are reusable. If the feature has UI, open the target's component preview (e.g. /ui/preview/all) to inventory available DS components before deciding what to build.
4. Dispatch bounded lanes (optional)
Split non-overlapping discovery — e.g. one lane on the reference trace, one on the target survey. No two lanes discover the same thing; the main agent owns synthesis, uncertainty calls, and the artifact.
The gap map artifact
Write one gap map per ported feature:
<artifacts-root>/specs/port/<feature-slug>-gapmap.md
Resolve <artifacts-root>: the *.code-workspace directory if one exists, else the per-context root (CONTEXT-MAP.md at repo root), else the repo root. <feature-slug> is kebab-case from the feature name, max ~4 words, ASCII. The gap map is an on-demand slug file — it does not consume the NNNN prompt/ADR sequence.
Nine sections, in order, ≤3 bullets each — link or cite evidence (file:line, route, migration, test), never paste it:
# Port Gap Map — <feature> (<REFERENCE-CODE> → <TARGET-CODE>)
## 1. Reference behaviour / workflow
- <behaviour/permission/state/data-effect> — evidence: `file:symbol`, route, migration, test.
- Navigation: where the feature lives in the reference and any moves the port implies.
## 2. Target current state
- <what exists today for this feature in the target> — evidence refs.
## 3. Missing / wrong in target
- <gap or divergence from the reference> — absent, partial, or behaving differently.
## 4. Reusable target code & DS components
- <existing target seam/service/component to extend> — path + why it fits.
- <design-system component from the target preview> — where it applies.
## 5. Tests needed
- Success paths, validation, permission checks, empty/error/success states, data effects, regressions to guard.
## 6. UI / design gaps vs reference (and forced DS deviations)
- <reference UI element> → <target DS equivalent>.
- Forced deviation: reference did X; target DS does Y; chose DS because <rule/source>.
## 7. Risks
- <behaviour, data, permission, or migration risk> and where it bites.
## 8. First slice
- One thin vertical slice that cuts through all layers and is testable on its own — not a layer, not a big-bang.
## 9. Open questions
- <evidence-derived question for /grill-with-docs>. List them; do not block on them.
Section rules (filled example bullets live in [references/gapmap-example.md](references/gapmap-example.md)):
- Every claim in sections 1–4 carries a concrete evidence ref; unproven claims are marked as inference, not fact.
- Section 5 seeds later acceptance criteria — cover every category its template bullet lists.
Output
Emit Stage / Found / Next / Needs user at each phase transition — one line per field. Final update:
Stage: port-feature — wrote specs/port/<feature-slug>-gapmap.md (<REFERENCE-CODE> → <TARGET-CODE>).
Found: <N> reference behaviours traced; target is <absent/partial/diverging>; <M> reusable target/DS pieces; <K> forced DS deviations; <R> risks.
Next: run /grill-with-docs on the gap map to challenge it and produce the ADR (next number in specs/adr/).
Needs user: <open questions to steer, or ambiguous reference/target mapping, or "none">.
Suggested next skills (optional):
- /grill-with-docs: challenge the gap map and record the porting decisions as an ADR.
- /prototype: if a UI/interaction open question needs to be seen or felt before planning.
Completion criteria
