Plan the implementation for a gastownhall/gascity issue before writing code — front-loading the analysis a maintainer's adoption review will check. Runs the competing-PR and architectural-refactor gates (don't start work that's already in flight or about to be superseded), maps blast radius (Phase 2), aligns the plan to repo conventions and the right test tier, and applies the design-capture discipline (land architectural work with an engdocs/design artifact). Produces a structured plan and the B-rule convention-trigger checklist. Self-contained — git + gh + the sibling skills, no internal tooling. Use when starting a new fix/feature branch.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Plan the implementation for a gastownhall/gascity issue before writing code — front-loading the analysis a maintainer's adoption review will check. Runs the competing-PR and architectural-refactor gates (don't start work that's already in flight or about to be superseded), maps blast radius (Phase 2), aligns the plan to repo conventions and the right test tier, and applies the design-capture discipline (land architectural work with an engdocs/design artifact). Produces a structured plan and the B-rule convention-trigger checklist. Self-contained — git + gh + the sibling skills, no internal tooling. Use when starting a new fix/feature branch.
Plan the Implementation
You have an issue number (from find-work, or one you
filed with write-issue) and you're about to implement
a change for gastownhall/gascity. This
skill front-loads the analysis the maintainer's adoption review will run — so you
address the concerns before writing code, when they're cheap.
The output is a written plan. No code is written until the plan is done and you
confirm it.
main below means the upstream main you're targeting — origin/main if origin
is gastownhall/gascity, else upstream/main.
Phase 1 — Issue analysis
Read the issue; extract what's broken, where it lives, why it matters.
gh issue view <number> --repo gastownhall/gascity --json title,body,labels,comments
gh issue list --repo gastownhall/gascity --search "<keywords>" --state all --limit 10
gh pr list --repo gastownhall/gascity --search "<keywords>" --state all -- 10
limit
Competing-PR gate (BLOCKING)
Before anything else, check whether an open PR already targets this issue, or
whether it's already fixed:
gh pr list --repo gastownhall/gascity --state open --search "<issue number>" --json number,title,author,createdAt
gh issue view <number> --repo gastownhall/gascity --json state
If a competing PR exists or the issue is closed, STOP. Pick a different issue
or, if you still think yours adds value, say so explicitly in the plan and decide
consciously. Don't silently start work someone else is already doing — it wastes
effort and creates merge conflicts.
Architectural-refactor gate (BLOCKING)
The competing-PR check catches issue-level duplicates; it misses area-level
ones. Before scoping a fix, check whether the file/package you'll touch sits
inside an active architectural refactor. If it does, a narrow fix gets superseded
and your time is wasted.
# Accepted / Implementing design docs:
grep -lE "^\| Status \|.*\b(Accepted|Implementing|Implemented)\b" engdocs/design/*.md
# Open maintainer PRs consolidating your target area (substitute a keyword# from the subsystem you're touching; skim hits for any that unify/refactor/# supersede it):
gh pr list --repo gastownhall/gascity --state open --search "<your-subsystem-keyword> in:title" --json number,title
# Recently-merged PRs that used "Supersedes" (the area is being consolidated):
gh pr list --repo gastownhall/gascity --state merged --search "supersedes in:body" --limit 5 --json number,title
If your area has an Accepted/Implementing design doc OR an open consolidation
PR touching it, STOP and choose one of:
Point-fix — a single-line change the refactor can absorb. Ask in the issue
whether that's wanted.
Wait for the refactor to land, then rebase.
Pivot to an issue outside the refactor area.
Read the relevant design doc before writing any code. Its Status field and
## Phase N headings tell you which parts are live and which are queued; a fix
landing in a queued phase won't survive rebase. (Gas City precedent: a single broad refactor
superseded eight narrow session-model PRs; another superseded two env-projection
PRs.)
Phase 2 — Blast radius
Map the impact surface with the map-blast-radius
skill: enumerate the functions you'll touch, their callers and execution contexts, the
config-field sync chain, domain-boundary crossings, and concurrency. Carry its
HIGH/MED findings into the plan's Risks and Blast radius sections.
Phase 3 — Convention alignment
Verify the plan follows these patterns before writing code:
Branch from the upstream main you're targeting; don't git checkout main first.
Phase 3.5 — Design-capture decision
Gas City's strongest contributions land architectural work with a design
artifact attached — maintainers author the engdocs/design/ canon, and a PR
that implements against (or proposes) a design doc clears review in one pass
instead of costing a "what's the intent here?" round-trip. This is the single
highest-leverage thing you can do to make an architectural PR land cleanly.
Does this change need a design doc?
Write (or update) an engdocs/design/<name>.md when any of these is true:
It introduces or changes a subsystem boundary or cross-cutting mechanism —
read-path/routing, store topology, supervisor or session lifecycle, a
provider/worker interface, the config override chain, an event/wire format, the
endpoint model.
It adds a new package or a new public contract/schema other components
or packs consume.
It changes behavior other components depend on — events.jsonl shape, a
CLI contract a pack reads, the bd+Dolt contract.
The work is cohesive feature-scale, not a point fix.
Skip the doc (a code-only PR is correct) when the change is a single-function bug
fix, test-only, docs-only, or a behavior-preserving mechanical refactor. Respect
KISS/YAGNI — never write a design doc for a one-liner.
Two capture mechanisms — know which is which
engdocs/design/*.md — forward-looking design proposal. This is the one a
contributor authors.
release-gates/*.md — per-change acceptance contract tied to a builder-fleet
deploy. You won't author these, but if your area already has one, cite it the
same way you'd cite a design doc.
If the area ALREADY has a design doc or release-gate
You found it in the Phase 1 architectural-refactor gate. Don't start a competing
doc — implement against it and cite it by path in the PR body and in the
commit that lands the core change (implements engdocs/design/<name>.md).
If it needs a NEW doc, draft the stub now — before code
Author it in the branch so it's reviewed with the diff, not bolted on after.
Confirm the live shape against any existing file in engdocs/design/ first, then:
cat > engdocs/design/<short-kebab-name>.md <<'MD'
---
title: "<Title Case Name>"
---
| Field | Value |
|---|---|
| Status | Proposed |
| Date | <YYYY-MM-DD> |
| Author(s) | <your handle> |
| Issue | #<number> |
| Supersedes | N/A |
## Summary
<2-4 sentences: what this changes and the one-line reason it's worth doing.>
## Problem
<What's broken or missing today, for a future maintainer with no context.>
## Design
<The approach. Name the subsystem boundaries it touches and the contract it
establishes — the "why this shape" the review otherwise reverse-engineers.>
## Alternatives considered
<At least one rejected option and why. Pre-empts "did you consider X?".>
MD
Register it — add one row to the Current Design Set table in
engdocs/design/index.md:
