Skip to content

oliver-kriska/claude-elixir-phoenix / plugins/rewrite/skills/roadmap

roadmap

Verified

Plan a rewrite as vertical slices and hand each one to /phx:plan as a requirements seed with binding decisions, contracts and acceptance criteria. Use after /rewrite:architect, or for the next slice.

FileKindSize
SKILL.mdskill md8.8 KB
references/seed-templates.mdmarkdown6.9 KB
references/slicing.mdmarkdown8.5 KB

references/seed-templates.md

View on GitHub
# Seed Templates — interview.md and scratchpad.md

`/phx:plan` detects `.claude/plans/{slug}/interview.md`. With `**Status**:
COMPLETE` it skips clarification and plans from the Summary and Coverage
Details. With `IN_PROGRESS` it asks only about the weak dimensions. These
templates keep that contract and add the rewrite's binding decisions.

## Coverage Rubric (score honestly)

| Dimension | 2 | 1 | 0 |
|-----------|---|---|---|
| What | every capability has goal sentences and acceptance probes | goals without probes | none |
| Why | purpose from features.md and the charter goal it serves | one of the two | none |
| Where | target contexts and modules, plus legacy anchors | only one side | none |
| How | ledger rows with verdicts and targets, ADRs linked | verdicts without targets | UNDECIDED rows remain |
| Edge Cases | negative probes, failure modes, crash windows | negative probes only | none |
| Scope | in, out, divergences and the next slice named | in and out only | none |

COMPLETE requires every dimension ≥1, total ≥8, no UNDECIDED ledger row
in the slice and no unresolved consequential decision: nothing the slice
depends on in the charter, ADR-000, linked ADRs or divergences is ASSUMED,
proposed or pending. Otherwise write IN_PROGRESS and list what is missing
under Open Questions. A COMPLETE score is never approval of a decision.

## Stable IDs

Every binding decision gets `D-NN` and every dead end `X-NN`, numbered per
slice from `01`. The same ID appears in `interview.md` and `scratchpad.md`,
and a re-seed keeps it. After `/phx:plan`, roadmap step 5 restores any ID
missing from `scratchpad.md` (retention), then maps each decision and
acceptance criterion to a plan task (coverage). An uncovered or
contradicted decision, or a task that adopts a dead end, keeps the slice
`seeded`.

## interview.md

```markdown
# Brainstorm: Rewrite slice {NN} — {name}

**Status**: COMPLETE | IN_PROGRESS
**Date**: {YYYY-MM-DD}
**Coverage**: What ████ | Why ████ | Where ███░ | How ████ | Edge ███░ | Scope ████
**Score**: {N}/12

> Requirements seed generated by `/rewrite:roadmap` from `.claude/rewrite/`.
> Not a human interview. Decisions marked ASSUMED were not approved by a person.
> Authoritative sources: `.claude/rewrite/architecture/` and `.claude/rewrite/ledger.md`.
> Write the plan to `.claude/plans/{slug}/plan.md`. Cite each `D-NN` in the task
> that implements it (or in a plan-wide constraint), and adopt no `X-NN`.

## Summary

{3–5 sentences: what this slice delivers in Elixir, which legacy behavior
it replaces, the guarantees it must keep, and how it will be verified.}

## Coverage Details

### What ({score}/2)
{capability goals F-xx with sub-behaviors}

### Why ({score}/2)
{purpose of each capability; the charter goal}

### Where ({score}/2)
{target contexts and modules from architecture.md; legacy anchors for reference only}

### How ({score}/2)
{the chosen design for this slice, from architecture.md and the ADRs}

### Edge Cases ({score}/2)
{negative probes, crash windows, concurrency, revocation}

### Scope ({score}/2)
{in scope; out of scope with the slice that owns it; divergences that apply}

## Binding Decisions

- DECISION: D-01 (ADR-004) durable work uses Oban, inserted in the same `Ecto.Multi` as the business write
- DECISION: D-02 (ADR-000) legacy session cookies stay valid; no forced logout

## Legacy Mechanism → Elixir Decision

| Ledger | Legacy mechanism (anchor) | Purpose | Verdict | Elixir target | Guarantees to keep |

## External Contracts

| Contract | Assertion | Witness the tests must implement |

## Oracle

Suites run against the port only, never the legacy app. Legacy tests are
translated into ExUnit, not run (slicing.md rule 11).

- **Legacy tests to translate**: {path:line per test, from contracts.md legacy witnesses, or `none`}
- **Black-box files that must pass**: {suite files or requests assigned to this slice, with the `--oracle` root} —
  `{exact command, e.g. hurl --test --continue-on-error --jobs 1 --variable host=http://localhost:4002 --variable uid=$(date +%s) hurl/auth.hurl}`; or `none`
- **Performance**: {harness script, or the port-only load script labelled "no legacy comparison", and the P0 gate it serves}; or `none`

## Transition Contract

{only for staged cutover or coexistence: write owner, routing, schema
authority, identity, jobs/events, data movement, cutover, rollback}

## Acceptance Criteria

{One checkbox per case, each with its own ID: `AC-N`. When a criterion names several cases (each token
shape, filter, route, fixture, black-box file or "does not change" clause), give each case its own
lettered ID: `AC-Na`, `AC-Nb`. In parentheses, cite every ledger ID the case witnesses. Cite every ID in
the mechanism and contract tables in at least one case. List only probes; a process step such as
scoring the ledger is not a case. These IDs are the slice's obligations: verify counts exactly these,
plus any omissions it finds.}

- [ ] AC-1 (M-04, C-11): {probe from features.md, positive}
- [ ] AC-2a (C-14): {negative probe, first case it names}
- [ ] AC-2b (C-14): {negative probe, second case}
- [ ] AC-3a (C-19): {`hurl/auth.hurl` passes whole against the release}

## Codebase Context

{target project facts: existing modules, mix.exs deps, conventions}

## Research Findings

### Approaches Found

#### Approach 1: {the accepted design}
- **Thesis**: {why it meets the goals and the bar}
- **Antithesis**: {its cost or risk, from the ADR}
- **Key files**: {target modules}

#### Rejected: X-02 {alternative from the ADR; also listed under Dead Ends}
- **Why rejected**: {ADR reasoning}

## Dead Ends

- DEAD-END: X-01 {translationese rejected for this slice, e.g. the legacy socket protocol in core code — ADR-006}

## Open Questions

- {UNDECIDED rows and missing evidence}
- {each unresolved decision: source (charter / ADR-000 / ADR-NNN / divergence ID), state (ASSUMED / proposed / pending), what it changes}

## Verification

`/rewrite:verify {NN}` scores every Acceptance Criteria item and every
contract witness above against fresh test evidence, and runs every
black-box file in `## Oracle` against the port. An obligation clears
only by passing, or by an accepted ADR or a user-approved AR record that
changes or retires it; ASSUMED never counts.

## Transcript

None. Generated from rewrite artifacts; see the sources above.
```

## scratchpad.md

phx appends to this file; keep each entry self-contained.

```markdown
# Scratchpad: rewrite-{NN}-{name}

Seeded by /rewrite:roadmap on {date}. Authoritative decisions live in
.claude/rewrite/architecture/; this file repeats the ones this slice needs.

### [00:00] DECISION: D-01 Durable work uses Oban in the same Ecto.Multi (ADR-004)
Rejected: Task.start, GenServer queues, Redis lists. Reason: jobs must
survive a crash between commit and enqueue (ledger M-12).

### [00:00] DEAD-END: X-01 Re-implementing the legacy socket protocol in core code
Only the SHIM module may speak it (ADR-006). Core uses Phoenix.PubSub.
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall