Writing pitchd rails plans

Writing Rails Implementation Plans

<objective> Produce **implementation plans** a skilled developer can follow without guessing your codebase: exact paths, real Ruby snippets, **RSpec** commands with expected outcomes, and **Rails-shaped** decomposition. Assume the reader knows Ruby and Rails but not your app — not that they need hand-holding on "what a test is."

Plans follow 37signals-style Rails: fat models, thin controllers, REST-first routing, Pundit at the boundary, Hotwire for HTML UX, no fake service layer — and the testing philosophy in skills/writing-tests/SKILL.md / rules/testing.mdc (RSpec + FactoryBot).

Voice: Write plans with DHH-level confidence. Make decisions; do not present options and defer to the reader. "Use a model concern here" — not "you might consider a concern". If the plugin rules say how to do something, the plan follows them — even if the current application does it differently. The plan shapes the code; the existing code does not shape the plan. That decisiveness applies to the finished plan document — the gates below (Requirements gate, Approach gate) are where doubt belongs. Interrogate first; write confidently after.

Plugin rules beat application patterns: If the current codebase uses service objects, custom routes, or test patterns that contradict plugin rules, the plan does not inherit those patterns. Name the correct approach and cite the rule. If an existing anti-pattern must be worked around for this task, say so explicitly and mark it as technical debt — do not normalize it. </objective>

Announce at start: "I'm using the writing-pitchd-rails-plans skill to create the implementation plan."

Requirements gate (before drafting anything)

Do not start writing the plan from a thin prompt. Grill the requirements first — a wrong assumption made here multiplies into every task, snippet, and spec below it.

1. Separate the problem from the mechanism. Restate the underlying problem in one sentence, in outcome terms — what the user or system needs, not how the prompt says to build it. If the request only describes a mechanism ("add a flag to X", "build a service that…"), ask what outcome it serves before drafting anything. A requirement that is really a pre-selected solution goes through the Approach gate below on the same footing as any other candidate.
2. Interrogate the request/spec for gaps across: the user-visible outcome, scope boundaries (what is explicitly out), affected resources and their relationships, authorization expectations (who may do what), UX surface (full page vs frame vs stream), data/migration implications, edge cases, and acceptance criteria.
3. Ask before drafting. For every gap or ambiguity, ask the user — use the harness's structured question tool when one is available (e.g. AskUserQuestion in Claude Code), which lets you present focused options for several decisions in one round; otherwise ask in chat, one question at a time. Do not pad the plan with guesses phrased as decisions.
4. Proceed without answers only on explicit instruction. If the user says "proceed with assumptions", record every assumption in the plan header under Assumptions: so the reviewer (Pass 1) can challenge them — an unstated assumption is invisible to review; a listed one is checkable.

A spec that already answers these questions (e.g. one produced by brainstorming-rails-omakase and signed off) passes this gate without re-interrogation — ask only about what the spec genuinely leaves open. The Approach gate below still runs even then: a signed-off spec approves a shape, so the gate's job shrinks to confirming the plan actually uses it.

Approach gate (before drafting anything)

The requirements gate settles what; this gate decides how — and whether the "how" that arrived in the prompt survives scrutiny. A plan can be fully convention-compliant and still be the wrong solution; this gate is where that gets caught, because the reviewer only ever sees the finished plan.

1. Read skills/rails-omakase-compass/SKILL.md first — before the file map, before any tasks. This read is mandatory for every plan, not just a row in the conventions table below.
2. A prompter-suggested approach is an input, not a decision. Evaluate it against the compass exactly as you would a candidate you generated yourself. "The user asked for it this way" is not a justification a reviewer can check.
3. State one credible alternative shape and a one-line reason the chosen approach wins. If no credible alternative exists, say so explicitly — that claim is itself checkable. Record the outcome in the plan header under Alternatives considered:.
4. Never fight the framework. If the chosen approach needs scaffolding to work around Rails, Turbo, or plugin defaults — custom plumbing where a convention exists, client-owned state for a server-owned flow, RPC where REST fits — the approach is wrong, not the framework. Route back to a Rails-native shape.
5. If the user's stated approach conflicts with the compass, stop and say so before drafting. Present the Rails-shaped alternative and let the user decide — a plan built on a disputed frame wastes every task below it. If the right shape is genuinely unclear, recommend a brainstorming-rails-omakase pass instead of planning around the uncertainty.

Primitives gate (before drafting anything)

Runs when the app has a docs/primitives/ tree (see rules/primitives.mdc and maintaining-primitives). If the tree does not exist, skip this gate — optionally mention bootstrapping-primitives once — and omit the Capability: header line below.

The reading contract is three files, never more: index.md, the one target capability doc, and compilation.md.

1. Read docs/primitives/index.md. Does an existing capability own this outcome? If yes, this plan is an amendment to that capability — never create a second doc whose intent overlaps an existing one (that is itself a plan defect the reviewer will flag). One capability per plan — always. Work spanning two capabilities is two plans (see When to plan — independent subsystems split): clause IDs are only unambiguous within one doc, and every downstream mechanism (header line, dispatch excerpts, review scope, close-out) targets exactly one doc. The reading-contract allowance for opening a second capability doc is for context, never a second target.

   This does not mean one plan per capability. The rule forbids a plan spanning two capabilities; the reverse is expected. A capability large enough to ship in stages gets several sequenced plans, each an amendment to the same doc serving its own clauses — which is what the spec's ## Delivery sequence enumerates (brainstorming-rails-omakase). Later plans leave a built doc at built and append their own provenance line, exactly like any other amendment.

2. Read docs/primitives/compilation.md. These are human-owned, app-wide constraints; the plan must not contradict them. If the right approach genuinely requires breaking one, stop and say so — the constraint changes by human amendment, not by a plan working around it.

3. Read (or create) the capability doc under docs/primitives/capabilities/<name>.md:

   • Exists (from brainstorming, status: shaping, or earlier work): confirm and extend. Classify every part of this plan against the Intent clauses — serves an existing clause / supersedes one (strike through, tombstone, new ID — never renumber or delete) / adds a new clause. Read ## Provenance before proposing an approach: do not re-litigate a recorded rejection or "fix" a recorded deliberate decision without saying so explicitly.
   • Missing, new feature: create it now. The requirements-gate answers are the Intent section — transcribe them as one-sentence clauses (I1, I2, …) instead of discarding them into chat history. Draft ## Shape (deltas only) from the approach-gate outcome.
   • Missing, existing feature (lazy backfill): create it from what the code demonstrably does plus the requirements-gate answers; Evaluations from specs that exist — shipped behaviour with no spec home gets a row marked unproven, same as a capture backfill (an honest test-gap record, not a blocker); provenance opens with YYYY-MM-DD — backfilled from existing behaviour; prior history in git. Set status: built — the feature is already shipped, and the plan being drafted is an amendment to it (final approval leaves built docs at built, same as a capture backfill). Gate-answer clauses are self-confirming — the user stated them live. Clauses reconstructed purely from code (behaviour this plan doesn't touch) are not: present them to the user for a quick confirmation as part of the gate questions, so nothing reconstructed ships as fact unconfirmed (capture parity).

4. Write Intent and Shape before drafting tasks. Tasks then cite clause IDs (serves I1, I4 / supersedes I4 → I5) instead of restating requirements — the plan is ephemeral; the capability doc is the durable record. When this gate creates a doc (new feature or lazy backfill), add its docs/primitives/index.md line at creation, same as capture — final approval then updates it.

Write points: during drafting this skill writes Intent and Shape; at final approval it also flips status: to planned, appends the one planned provenance line, and syncs index.md (see At final approval below). Evaluations rows, status: built, and the built provenance line belong to execution close-out (executing-pitchd-rails-plan); do not fill them from intention. The one exception is the lazy backfill above: Evaluations rows transcribed from already-existing specs record reality, not intention, and are correct to write at plan time.

Philosophy (DHH / Pitchd Rails)

• Vertical slices over layers: Prefer tasks that complete one resource's slice (schema → model → policy → routes → controller → views → specs) over scattering "all models, then all controllers."
• REST is the vocabulary: New behavior is usually new resources or standard CRUD, not RPC routes — see rules/routes.mdc. If the plan adds post :publish, it needs a one-line justification or a nested resource / update shape instead.
• Domain logic lives on the model (and concerns, form objects, jobs — not app/services wrappers). Plans must not introduce SomethingService#call that only forwards to Active Record — see rules/services.mdc.
• Authorization is explicit: Tasks must name policy changes (authorize, policy_scope) — see rules/policies.mdc.
• UI is server-rendered first: Turbo Drive → Frames → Streams as complexity grows — see rules/hotwire.mdc, skills/writing-hotwire/SKILL.md, rules/views.mdc, rules/javascript.mdc.
• Tests are behaviour-first: System spec for user-visible flows when possible; request / model / policy specs only where skills/writing-tests/SKILL.md says — one home per behaviour, no duplicate coverage across layers (rules/testing.mdc).

When to plan

• Run in a clean branch or worktree when the change is large enough that mainline noise would confuse review (optional but recommended).
• If the spec spans independent subsystems, split into separate plans (one deployable slice each), or separate epics with clear boundaries.
• If the spec has a ## Delivery sequence, it has already done that decomposition — plan one slice, not the whole spec. Take the slice's clause IDs as this plan's scope; everything outside them is a later plan, not deferred work to mention in this one. If the spec covers a large capability and has no delivery sequence, say so and propose the split before drafting — a single plan for a multi-slice feature is the large-plan problem the sequence exists to prevent.

PR and deployment scope

The unit of delivery is the pull request. The spec's ## Delivery sequence (brainstorming-rails-omakase) decomposes a capability into deployable slices — one plan each; this section sizes what one plan produces. The best practice is fixed here so every plan applies the same one — decide the delivery shape before writing tasks and declare it in the header's Delivery: line:

1. One plan, one PR, one deployable slice — by default. The whole task list lands as a single PR a reviewer can hold in their head in one sitting. Main stays deployable after every merge.
2. Size heuristic: target ≤ ~400 changed lines of application code per PR (specs ride along and don't count against the target; generated files excluded). Past that, review quality drops — split. Crossing ~800 is not a judgment call: the slice is too big — send it back to the spec's Delivery sequence and split it into two slices (two plans), by seam, not by layer.
3. Split by dependency seam, not by layer. Whether cutting slices at the sequence level or drawing PR boundaries inside one plan, cut sequentially shippable vertical increments, each independently valuable and safe with only the PRs before it. Never "all models PR, then all controllers PR", and never a PR that is only correct once a future PR lands.
4. Schema changes follow expand → migrate → contract across PRs. The additive migration ships in the same PR as the code that uses it; destructive or contracting steps (dropping columns, tightening constraints on old data) go in a follow-up PR after the deploy proves them safe — see rules/migrations.mdc.
5. Dark until wired — no feature-flag framework. For multi-PR features, earlier PRs ship code that is unreachable (routes and links not yet wired); the final PR wires the entry point. Omakase incremental delivery without a flag dependency.

Save location

Default: docs/plans/YYYY-MM-DD-<feature-name>.md in the app repo (create docs/plans if needed). User or team conventions override this path.

Plugin conventions to apply

Reading plugin files: Before your first Read from the table below, resolve the correct path prefix via resolving-plugin-root — bare relative paths only resolve correctly against Cursor's workspace root or a raw checkout; a Claude Code plugin install needs the resolved prefix instead.

This table is a gate, not a suggestion. Before writing tasks for an area, read the matching row (rule + skill). Do not write migration tasks before rules/migrations.mdc, controller tasks before rules/controllers.mdc, spec tasks before skills/writing-tests/SKILL.md — and so on for every row the plan touches. A plan that specifies code for an area whose conventions were never loaded is not ready for review, regardless of how plausible the snippets look:

Area	Read
Architecture, omakase fit, boundaries ("whether" before "how")	skills/rails-omakase-compass/SKILL.md
Models, domain verbs, state-as-records	rules/models.mdc, skills/writing-models/SKILL.md
Routes, shallow nesting, REST	rules/routes.mdc, skills/writing-routes/SKILL.md
Controllers, params, Hotwire response order	rules/controllers.mdc, skills/writing-controllers/SKILL.md
Pundit	rules/policies.mdc, skills/writing-policies/SKILL.md
No service layer / where logic goes	rules/services.mdc
Tests (RSpec, FactoryBot, spec types)	rules/testing.mdc, skills/writing-tests/SKILL.md
Hotwire, Stimulus	rules/hotwire.mdc, skills/writing-hotwire/SKILL.md
Views, partials, components discipline	rules/views.mdc, skills/writing-views/SKILL.md
Tailwind / CSS	rules/css-tailwind.mdc, skills/writing-css-tailwind/SKILL.md
JavaScript	rules/javascript.mdc, skills/writing-javascript/SKILL.md
I18n	rules/i18n.mdc, skills/writing-i18n/SKILL.md
Mailers	rules/mailers.mdc, skills/writing-mailers/SKILL.md
Background jobs	rules/jobs.mdc, skills/writing-jobs/SKILL.md
Migrations	rules/migrations.mdc, skills/writing-migrations/SKILL.md
Naming (classes, methods, columns, routes, specs)	rules/naming.mdc, skills/writing-naming-conventions/SKILL.md
Linting	rules/rubocop.mdc, skills/running-rubocop/SKILL.md

Supplementary reference (optional)

When rails-omakase-compass, this skill's philosophy section, and the scoped rules/*.mdc / writing-* rows above still leave a Rails best-practice gap, two sources are available — use the one that fits:

• skills/referencing-unofficial-37signals-guide/SKILL.md — for 37signals / Fizzy-derived patterns and philosophy not spelled out in the plugin (README TOC → raw .md).
• skills/referencing-rails-guides/SKILL.md — for authoritative Rails API and feature docs (GitHub API index → specific guide .md).

Both inform the plan — they do not override plugin rules or skills; tactics in this plugin win on HOW, same as the compass conflict rule in implementing-pitchd-rails. If a fetch fails or returns nothing usable, report that; do not invent or assert content.

Map files before tasks

Before checkbox tasks, add a short file map: what will be created or changed and why (single responsibility per file). Prefer cohesion with the existing app: if the codebase uses larger files, do not split "for SRP" unless the spec or file size demands it.

• Files that change together should live together (Rails default: by resource/feature, not by abstract "layer").
• Interfaces are REST + Active Record + Pundit — not internal JavaScript APIs unless the spec is explicitly an API feature.

Task order (repeatable template)

Order tasks by dependency, not arbitrary numbering:

1. Migration / schema — if the data shape changes (db/migrate/...).
2. Model — associations, domain verbs, transactions, scopes (app/models/..., concerns under app/models/concerns/).
3. Policy — if authorization or scoping changes (app/policies/...).
4. Routes — config/routes.rb (resources, shallow: true, etc.).
5. Controller — REST actions only; custom actions are rare and justified.
6. Views / partials — app/views/... per skills/writing-views/SKILL.md.
7. Hotwire / Stimulus — only if the UX needs frames, streams, or client behavior (skills/writing-hotwire/SKILL.md).
8. I18n — user-facing copy (rules/i18n.mdc) when adding or changing strings.
9. Mailer — only if the spec requires email (rules/mailers.mdc).
10. Jobs — only if the spec requires background processing (rules/jobs.mdc).
11. Tests — spec type per skills/writing-tests/SKILL.md: system spec for user-visible flows, model/request/policy specs for their respective layers. Each task should include the test step inline (write failing test → red → implement → green); this step is the reminder to include tests in every task, not only at the end.

Each task should be a coherent slice that can reach a green checkpoint (tests passing), not a ritual sequence of micro-edits with no runnable state between steps.

Granularity

Target meaningful steps (often 5–30 minutes), not only 2–5 minute micro-steps:

• Write failing test → run RED → minimal implementation → run GREEN is the core loop; group steps so one task might include the model + policy + controller change if they belong together as one vertical slice. Sequencing and how work is broken into deliverables are up to the user and the implementing agent.

Plan document header

Every plan MUST start with this header (adjust paths if your repo uses a different docs location):

# [Feature Name] Implementation Plan

> Steps use checkbox (`- [ ]`) syntax for tracking. When writing or updating specs,
> follow **`skills/writing-tests/SKILL.md`** and **`rules/testing.mdc`**. Prefer
> **system specs** for user-visible behaviour; add request, model, or policy specs
> only per the decision tree in that skill. **One behaviour, one spec home.**
> How the plan is followed or sequenced is up to the user and the implementing agent.

**Capability:** `docs/primitives/capabilities/<name>.md` — serves I1–I4
[Clause IDs this plan serves, supersedes, or adds. Omit this line only when
the app has no `docs/primitives/` tree.]

**Problem:** [One sentence — the underlying need in the user's terms: what
breaks or is missing without this. Distinct from Goal, which describes the
outcome of the chosen solution.]

**Goal:** [One sentence — user-visible or system outcome]

**Approach:** [2–3 sentences — REST resources, where domain logic lives (model,
form object, job), Hotwire surface]

**Alternatives considered:** [1–2 rejected shapes with a one-line reason each,
or an explicit "none credible" — an unstated frame is invisible to review;
a listed one is checkable.]

**Rails shape:** [Key models, resources, policies]

**Delivery:** [`one PR` (default). Multi-PR boundaries are the rare
mechanical case — e.g. `PR 1: Tasks 1–4; PR 2: Task 5 (contract-step
migration after deploy)` — each boundary an independently deployable vertical
increment. A feature-scope overrun is not a multi-PR plan; it goes back to
the spec's Delivery sequence as another slice. See PR and deployment scope.]

**Assumptions:** [Only when the user said to proceed without answering
requirements-gate questions — list each assumption so review can challenge it.
Omit this line otherwise.]

**Conventions:** `skills/rails-omakase-compass/SKILL.md` (shape), `rules/models.mdc`,
`rules/routes.mdc`, `rules/controllers.mdc`, `rules/policies.mdc`, `rules/services.mdc`,
`rules/testing.mdc`, `rules/hotwire.mdc` (and UI rules as needed — see table above)

---

Task structure

Use Ruby in code fences and bundle exec rspec for commands — never Python/pytest unless the spec is literally a non-Ruby subproject.

### Task N: [Resource or slice name] (serves I1, I4)

[The clause citation replaces restated requirements — the capability doc owns
intent. Use `(supersedes I4 → I5)` when the task changes intent. Omit the
parenthetical only when the app has no primitives tree.]

**Files:**
- Create: `db/migrate/XXXXXXXXXXXXXX_add_foo_to_bars.rb`
- Modify: `app/models/bar.rb`
- Modify: `app/policies/bar_policy.rb`
- Modify: `config/routes.rb`
- Modify: `app/controllers/bars_controller.rb`
- Create: `spec/system/bars_spec.rb` (or the spec type chosen per writing-tests)

- [ ] **Step 1: Write the failing test** (system / request / model / policy per `skills/writing-tests/SKILL.md`)

```ruby
# Illustrative — align with the app's helpers, factories, and I18n keys.
RSpec.describe "A focused behaviour", type: :system do
  it "does what the user cares about" do
    # ...
  end
end
```

- [ ] **Step 2: Run to verify RED**

Run: `bundle exec rspec spec/system/bars_spec.rb:12`
Expected: FAIL — [specific expectation, e.g. missing route, undefined method]

- [ ] **Step 3: Minimal implementation** (model + policy + route + controller as one slice when appropriate)

```ruby
# Show real code the implementer will add or change — no placeholders.
```

- [ ] **Step 4: Run to verify GREEN**

Run: `bundle exec rspec spec/system/bars_spec.rb:12`
Expected: PASS

No placeholders

These are plan failures — fix before sharing:

• "TBD", "TODO", "implement later", "add validation as needed"
• "Write tests" without concrete spec code and file path
• "Similar to Task N" — repeat necessary snippets; tasks may be read out of order
• Steps that only name a layer ("add controller logic") without what and where
• Types, methods, or policies referenced but never defined in an earlier task
• Introducing service objects, repository layers, or RPC routes without matching justification and alignment with rules/services.mdc / rules/routes.mdc

Rails anti-patterns to reject in plans

Reject or rewrite tasks that follow these patterns — regardless of whether the current application already does them. If an anti-pattern is already present in the codebase, do not extend it. Name it, cite the rule, and route around it.

• app/services wrappers that only call Active Record — use model verbs, form objects, or jobs (rules/services.mdc).
• Custom member routes for state that belongs in update or a small resource (post :publish vs PublicationsController) without justification (rules/routes.mdc).
• Duplicate system + request + model coverage for the same behaviour (rules/testing.mdc).
• Standalone not_to assertions that only prove an element is absent — every spec must assert positive behaviour the user sees; not_to is a secondary side-effect assertion, not a primary one (rules/testing.mdc).
• Turbo Streams before redirect / frame solutions when the UX allows (rules/controllers.mdc, skills/writing-hotwire/SKILL.md).
• One vertical slice split across many tasks that never pass CI in between.
• The same method or behaviour defined on more than one entity across tasks — shared behaviour gets one home: a concern or the owning model (rules/models.mdc). Per-entity copies drift the moment one changes; tasks drafted entity-by-entity hide this, so it must be caught at the plan level.

Self-review

After drafting the plan:

1. Spec coverage: Every requirement maps to at least one task (list gaps).
2. Placeholder scan: Search for forbidden vague phrases (see above).
3. Naming consistency: Method names, policy methods, and route helpers match across tasks (no publish vs publish! drift unless intentional).
4. Duplication scan: Read the plan as a whole — not task by task — and search for the same method name or behaviour defined on more than one model or entity across tasks. Each hit is a defect: rewrite the tasks so the behaviour has one home — a concern or the owning model (rules/models.mdc) — and the other tasks reference it.
5. Anti-pattern scan: Check that no task normalizes a current application anti-pattern — even if the existing code does it. Flag and route around it.
6. Convention coverage: List every area the plan touches (migrations, models, policies, routes, controllers, views, Hotwire, i18n, mailers, jobs, tests, …) and confirm you read that area's rule + skill from the table before writing its tasks. Any area written from memory: re-read the row and re-check those tasks now.
7. Frame check: Re-read the Problem: line. Confirm every task serves it, no task exists only to prop up the chosen mechanism, and nothing in the plan works around a framework default. If a task fails this check, the issue is usually the approach, not the task — go back through the Approach gate before patching.
8. Delivery check: Estimate the changed application-code lines the plan produces and hold it against PR and deployment scope: one PR under the ~400-line target, or declared seam-based boundaries in the Delivery: line, each independently deployable. A migration whose contract step rides in the same PR as its expand step, or a task only safe once a later PR lands, fails this check. An estimate past ~800 means the slice itself is too big — route it back to the spec's Delivery sequence as a split, not a fatter plan.
9. Primitives trace (when the tree exists): Every task's behaviour maps to an active Intent clause in the capability doc; every clause this plan touches appears in the header's Capability: line; supersessions are explicit in both plan and doc; nothing contradicts compilation.md or the doc's recorded Shape and Provenance. Untraceable behaviour means either a missing clause (add it) or scope creep (cut it).

Fix issues inline; add tasks for missing requirements.

Plan review

Happy path (default): Draft → Pass 1 → apply feedback to the plan file → Pass 2 only when required (see Pass 2).

User revisions (at any point)

If the user requests changes to the plan at any point during the session, enter Revision mode (see ## Revision mode below). After the revision is applied and the scoped review is complete, resume or close the pass flow as described there.

Pass 1 — Feature / plan shape (pitchd-rails-reviewer)

After drafting, delegate to pitchd-rails-reviewer (agents/pitchd-rails-reviewer.md — Cursor subagents). Canonical workflow and report format: skills/reviewing-pitchd-rails/SKILL.md.

Delegation prompt must include:

Field	Value
Phase	plan (or both if you also want implementation-adjacent checks)
Plan path	Path to this plan file (e.g. docs/plans/2026-04-09-feature.md)
Spec path	Path to the spec or requirements doc, or none
Scope	The plan file path again, or full plan
User revisions	(optional) Bullet summary of what the user changed — reviewer focuses only on these sections. Example: - Task 3: replaced form object with model verb; - File map: removed app/forms/publish_form.rb

Invoke with /pitchd-rails-reviewer plus that context, or use the Task tool.

Incorporate Approved items or address Issues found by editing the plan (tasks, file map, snippets). "Implemented" at this stage means feedback is applied in the plan document — not yet shipping code.

Present a brief summary to the user: Pass 1 outcome and what was changed in the plan.

Pass 2 — Final sign-off (pitchd-rails-reviewer, conditional)

When: Skip Pass 2 only when Pass 1 required no edits to the plan. Run Pass 2 when you incorporated Pass 1 recommendations or user revisions materially changed the plan (tasks added/removed, approach changed, file map altered).

Then delegate to pitchd-rails-reviewer again.

Initial Pass 2 call:

Field	Value
Phase	plan (use both only if you also need implementation-shaped checks)
Plan path	Updated plan file
Spec path	Unchanged from Pass 1, or none
Scope	full plan — state that this is final sign-off before implementation and whether prompted by Pass 1 edits or user revisions
User revisions	(optional) Bullet summary — context only: the reviewer reads the full plan; User revisions tells them where to pay extra attention, not where to stop

Loop call (after fixing Pass 2 issues):

Field	Value
Phase	same as initial
Plan path	Updated plan file
Spec path	Unchanged, or none
Scope	The changed sections only (e.g. Task 3 — replaced approach, File map — removed entry)
User revisions	Bullet list of exactly what was fixed — the reviewer reads only these sections

Treat the outcome as final plan approval before implementation. If Pass 2 raises issues, fix the plan and re-run scoped to the fixes only — set User revisions to a bullet list of what changed and Scope to those sections; do not send the full plan again. One scoped fix cycle is usually enough — if a second loop is needed, repeat the same scoped pattern.

At final approval — primitives sync (when the tree exists)

Once the plan is finally approved (Pass 1 with no edits, or Pass 2 Approved):

1. Flip the capability doc's frontmatter to status: planned (leave built docs at built — an amendment plan does not un-build a capability).

2. Append one provenance line covering the whole planning session — provenance records events, not edits; five drafting revisions are still one planned event:

   - YYYY-MM-DD — planned: docs/plans/YYYY-MM-DD-<feature>.md. [Rejected
     alternatives from the header's Alternatives considered, one line.]
   

3. Add or update the capability's line in docs/primitives/index.md.

Revision mode

When to enter revision mode

After this skill has run in the current chat session — whether mid-pass, after findings have been presented, or after final sign-off — treat any user message as a revision request if it matches phrases like — but not limited to — these:

"this needs changing", "that's not right", "can you fix…", "this is wrong", "update this", "adjust…", "tweak…", "it should do X instead", "change the…", "rewrite task N", "the approach is wrong"

Do not restart the full pass flow. When the message is specific enough to act on — what to change, where, and what "fixed" looks like — treat it as the complete description of a self-contained plan revision and proceed immediately, without asking which pass or section it relates to. When the message is vague on any of those, ask for clarification first — do not assume. A guessed revision that lands wrong costs more than one question.

Revision task loop

R1. Scope the revision

Extract from the user's message:

• What to change — the section, task, snippet, approach, or field they flagged.
• Where in the plan — infer from context (last pass reviewed, section mentioned).
• Acceptance — what "fixed" looks like (derive from the user's wording; do not ask for a formal AC).

If any of the three is unclear from the message plus session context, ask — do not assume. One focused message (the structured question tool works well here) covering everything unclear; proceed once answered.

R2. Edit the plan

Apply the change directly to the plan document on disk. This skill edits the plan; there is no implementor subagent for plan edits. Scope the edit tightly — do not rewrite unrelated sections or re-run the self-review on unchanged content.

Primitives sync (when the tree exists): classify the revision. Tactics only (snippets, file map, task order) → capability doc untouched. Changes to what the feature does (scope, outcome) → amend the Intent clauses in the same edit as the plan (add / supersede; pre-approval clauses not yet referenced by an approved plan may simply be edited). No provenance line per revision — the single planned line at final approval covers the session.

After editing:

• Summarize what changed — concise bullet list of which sections were affected (header fields, file map, task list, snippets, approach, deferred items, etc.), including any Intent clause changes in the capability doc.

R3. Delegate a scoped review

Invoke pitchd-rails-reviewer with:

• Phase: plan
• Plan path: the plan file.
• Spec path: as used earlier in this session, or none.
• Scope: the changed sections only (not the full plan).
• User revisions: the bullet summary from R2 — the reviewer focuses only on what changed.

Exception: if no full pass has yet reviewed the plan (the revision happened before Pass 1 ever ran), send a full-scope review — scoping to changed sections only applies once at least one full pass is on record.

R4. Branch on status

• Status: Approved → report back to the user (see R5 below), then resume or close the pass flow:
  • If the revision materially changed plan scope (tasks added or removed, approach changed, file map altered) and Pass 2 has already run, run Pass 2 again on the full plan before treating the plan as finally approved.
  • Otherwise, continue from wherever the pass flow was interrupted.
• Issues found → apply the reviewer's feedback to the plan and loop from R2 until Approved.

R5. Revision completion report

Deliver a brief summary:

• What was changed and in which plan sections.
• Reviewer status (Approved after N iteration(s)).
• Any non-blocking notes from the reviewer worth the user knowing.
• Whether the revision triggers a Pass 2 re-run (and if so, that it will run next).

Do not re-present the full findings from earlier passes — this is a targeted revision report only. If the user's follow-up triggers another revision, repeat from R1.

---

Executing the plan (orchestration)

To run an approved plan without the main agent writing app code, use ../executing-pitchd-rails-plan/SKILL.md: delegate each task to pitchd-rails-implementor, review with pitchd-rails-reviewer in a loop until Approved, then hand off to the user for sign-off. In step-by-step mode that skill stops after each Approved task for the user to review and commit it — so each task in this plan is also a commit checkpoint, which is what the granularity guidance above is sizing.