# loop-plan

> Write a phased, code-grounded implementation plan for large work, so a fresh session can carry it out without guessing.

`loop-plan` turns a large request into a phased plan file. Each phase names the files, symbols, tests and commands it depends on, and each acceptance criterion can be checked by a command or a real run. The skill plans only. It does not change application code.

## When to use it

Use it for large work:

- several features, or one feature that touches many files or components
- work that spans sessions and needs phase boundaries you can resume from

Do not use it for a small fix or a single-feature change. Make the change directly with tests, then run `/review-impl` (Claude Code) or `$review-impl` (Codex) if you want a review. The skill tells you this when the request is small, and plans it only if you still ask.

## Invoke it

**Claude Code**

```text
/loop-plan move the tag storage in atlas-notes from one column to a join table
```

**Codex**

```text
$loop-plan move the tag storage in atlas-notes from one column to a join table
```

Name the target and anything that must not change. You do not need a full specification: the skill asks for corrections at three points (see [Talking with the skill](#talking-with-the-skill)).

## What it works out by itself

- The repository instructions (`CLAUDE.md` or `AGENTS.md`), `git status`, recent history, and the files, symbols, callers and tests the change touches.
- Whether a library or platform behavior has been seen to work in this repository. When it has not, it runs a small spike under `.cross-review/spikes/<plan-name>/` and records the result in `Feasibility evidence`.
- The design that fits the existing patterns, reusing helpers by name. When the existing pattern is itself the problem, it gives you two options (patch within the pattern, or move to the standard) and waits for your choice.
- Where the plan goes. It runs the `plans` command, which creates `.cross-review/plans/` and prints the folder, then writes `<kebab-case-summary>-plan.md` there. The name describes the work, for example `migrate-tags-plan.md`, never a generic `plan.md`.

It asks you only for material decisions: product behavior, API, schema, dependencies, compatibility, or operations. Hard stops in a plan are reserved for data loss, security, and irreversible actions. Anything else that cannot be verified becomes a recorded assumption with a default and a fallback.

## What the plan contains

The plan has these sections, in this order:

| Section                                    | What it holds                                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Target, Scope, Invariants, Fixed decisions | What the work achieves, what it leaves out, and choices the implementation must not change on its own |
| Baseline                                   | Completed work, and the real duration of each gate command                                            |
| Design and project patterns                | The pattern each change follows, with its path or symbol                                              |
| Feasibility evidence                       | Assumption, spike or source, result, date                                                             |
| Capacity                                   | Limits the plan sets, or `N/A`                                                                        |
| Global Gates                               | Commands run once on the final commit                                                                 |
| Review checkpoints                         | Which phases end with a review, and a final review of the whole diff                                  |
| Plan Review                                | `pending` until a review or you approve the plan                                                      |
| Phase 1 to N                               | The phase blocks described below                                                                      |
| Completion Criteria                        | The whole-plan outcome, with at least one end-to-end scenario and its expected output                 |
| Progress Log                               | Written during implementation: one line per phase, dated `Decision:` and `Discovery:` lines           |

Each phase has: Goal, Current behavior and gap, Evidence, Pattern, Dependencies, Files and symbols, Behavioral contract, Documentation, Tests first, Anti-shortcut coverage, Implementation obligations, Acceptance criteria, Focused verification, Phase gates, Review, and Commit. Acceptance criteria are checkboxes that must be binary, each with the proof that shows it (a test, a real run, or an inspection):

```markdown
- [ ] AC-1: a tag added to a note is returned with that note — proven by a test in the notes store suite
```

## Talking with the skill

The skill stops three times so you can correct it:

1. **After discovery.** It restates the target, what is out of scope, and its assumptions.
2. **After the spikes.** It shows the main design decisions, especially a patch versus a standard, and any breaking change.
3. **At handoff.** It gives the plan path, whether git keeps the plan, the dashboard link when one is open, the phase count, and the review status. You then choose whether to run `/review-plan` or approve the plan yourself.

Each decision comes on its own, in five parts: context, problem, options with cost and risk, recommendation, and what happens next if you agree. A generic “ok” approves nothing that was not presented.

## After the plan

1. Run `/review-plan` (or `$review-plan`) on the plan file. See [review-plan](https://cross-review.tlelabs.com/docs/skills/review-plan/).
2. When the reviewer approves, `Plan Review` reads `APPROVE (review-plan <session id>, <date>)`. If you approve directly, it reads `APPROVE (user, <date>)`.
3. Run `/loop-implement` (or `$loop-implement`). It starts only from an approved plan. See [loop-implement](https://cross-review.tlelabs.com/docs/skills/loop-implement/).

## What you can say in chat

| You say                              | What happens                                                                 |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| A correction to the target or scope  | The skill updates the plan and continues                                     |
| “Use option 2” (or any named option) | The skill records the decision and changes the affected sections             |
| “Approve it”                         | The skill writes `APPROVE (user, <date>)` after showing what it is approving |
| “Run the review first”               | The skill hands over to `/review-plan`                                       |

## Example

Project: atlas-notes. Tags are stored as one comma-separated column on the notes table.

Request: `/loop-plan move the tag storage in atlas-notes from one column to a join table`

The skill writes `.cross-review/plans/move-tags-to-join-table-plan.md` with three phases:

1. Schema and migration. It includes a retry path for a partial run and says that rerunning is safe.
2. Read path: notes return their tags from the join table.
3. Write path and removal of the old column.

Review checkpoints are after phase 1 (the migration changes state) and a final review of the cumulative diff. The plan review is still `pending` until it is approved.

See [Plans](https://cross-review.tlelabs.com/docs/guides/plans/) for where plans live, how git treats them, and how the dashboard shows them.