pep

What this skill does

# PEP Workflow

A PEP is a markdown file at `docs/peps/PEP-NNN-slug.md`. One document covers two
modes: investigation (you don't know the shape yet) and execution (you do, and
here's the plan). Status line tracks which mode it's in. There is no engine, no
state.db, no separate "spike" document type. Same file, same skill, different
sections filled in.

The skill is generic. Per-repo specifics live in `agent-constraints/` at the
repo root.

## Determine Action

- **"spike <topic>"**, **"investigate <topic>"**, **"explore <topic>"**, **"look into <topic>"**, **"scout"**, **"research"**, **"scope out"**, **"figure out"** → Create in investigation mode (jump to Create)
- **"create PEP"** or **"document this"** → Create (jump to Create)
- **"update PEP"** or **"mark done"** → Update existing (jump to Update)
- **"PEP status"** → Show status (jump to Status)
- **"run PEP"** or **"run wave"** → Run Wave (jump to Run Wave)

## Repository Configuration

Before creating or executing a PEP, check for these files at the repo root and
read the ones that exist:

- `agent-constraints/planning-conventions.md` - analysis, documentation, and test strategy requirements
- `agent-constraints/adversarial-dimensions.md` - review criteria specific to this repo
- `agent-constraints/implementation-conventions.md` - build, verify, and PR conventions
- `agent-constraints/triage-conventions.md` - codebase exploration rules

Also read, if present, for domain vocabulary and settled decisions:

- `CONTEXT.md` (or `CONTEXT-MAP.md`) - the repo's domain glossary. Use its
  terms in the PEP so names stay consistent; the `grill` skill maintains it.
- `docs/adr/` - recorded architectural decisions. Don't re-plan around a
  settled ADR; cite it instead.

Per-repo files win over skill defaults; partial existence is fine, fall back per
file. Always cite which override applied under the PEP's `Conventions applied`
line.

## Two Modes of the Same Document

A PEP can be in one of two modes at any moment. The status line says which.

**Investigation mode**: status is `Investigating`. The PEP has Context + Open
Questions + Findings. No waves yet. The deliverable is a decision, not a code
change. Closes as one of:
- `Inlined as <commit-sha>` (investigation produced a small fix, committed inline)
- `Parked` (worth doing later, here's why we stopped, here's the trigger for resuming)
- `Abandoned` (decided not to do it, here's why)
- `Resolved as <free-form>` (e.g. "spawned PEP-007", "answered in Decisions Log, no code change needed")

**Plan mode**: status is `Draft | In Review | Approved | In Progress | Done`.
The PEP has Invariants + Waves + Gates. Adversarial review is mandatory before
moving from `In Review` to `Approved`. The deliverable is shipped code.

A PEP can start in investigation and graduate to plan mode by adding Waves and
re-running adversarial review. Or stay in investigation forever and close as
Parked / Abandoned / Resolved. There is no formal "promotion" command; the
status line and the section content are the only signals.

## Create

1. Find the docs directory. Default is `docs/peps/` at the repo root. If the
   repo uses a different convention (read `CLAUDE.md`), use that.
2. Glob `<docs>/PEP-*.md` to find the highest number, increment for next. First
   PEP in a repo is `PEP-001`.
3. Read repo `CLAUDE.md` and any `agent-constraints/*.md` files that exist.
4. Decide mode from the user's trigger:
   - "spike / investigate / explore / scout / look into / scope out / figure out / research" → start in **investigation mode**, status `Investigating`.
   - "create PEP / document this" → start in **plan mode**, status `Draft`.
   If unclear, default to investigation mode. It's cheaper to add waves later
   than to over-commit early.
5. Write the PEP using the appropriate skeleton from [references/template.md](references/template.md). Do not improvise the markdown shape.
6. **If plan mode:** immediately run the adversarial review pass (see [references/adversarial-review.md](references/adversarial-review.md)) before presenting to the human. Never present an unreviewed plan.
7. **If investigation mode:** no adversarial review yet. Present the Context + Open Questions and ask the human what to investigate first.

## Investigation Mode Workflow

1. Read the relevant code, run reconnaissance commands, follow references.
2. Append entries under `## Findings` as you learn. Each finding cites a file
   path and line number where applicable.
3. Update the `## Open Questions` list: resolved questions move to Findings with
   the answer; new questions append.
4. When the investigation is conclusive, write a `## Recommendation` section
   stating what should happen next. Recommendations are one of:
   - **Promote to plan mode** (add Invariants + Waves, run adversarial review).
   - **Close as Inlined**: investigation surfaced a small fix that's already
     committed. Record the commit sha.
   - **Close as Parked**: not now, here's the trigger for resuming.
   - **Close as Abandoned**: not ever, here's why.
   - **Close as Resolved as <free-form>**: e.g. "spawned PEP-007 for the
     real work", "answered without code change, see Decisions Log".
5. Present the recommendation as a verdict (see [Presenting to the Human](#presenting-to-the-human)).
6. On human approval, update the status line accordingly. If promoting to plan
   mode, jump to Wave Authoring.

## Wave Authoring (plan mode)

A wave is a sweep of work followed by a gate. Each wave must have: a name
describing what it does (not a generic label), a primary Shape (see
[references/wave-shapes.md](references/wave-shapes.md)), Files, Risks, Rollback
(mandatory for Config and Migration shapes), and one or more Gates whose form
depends on the Shape.

Choose the right number of waves based on complexity. 1 wave for a config
change or simple fix. 2 for a new feature with tests. 3+ for cross-cutting
changes. Do not default to 3.

Cross-wave contracts ("public API stays unchanged", "old code keeps working
between deploys") go in the PEP's `Invariants` section, not buried in per-wave
Risks.

For browser/UI gates: make them executable. Specify the URL, the steps to
perform (click X, type Y), and the expected outcome. "Verify it works in the
browser" is not a gate.

## Adversarial Review (mandatory before approval)

After writing or iterating the plan, run adversarial review before presenting
to the human. See [references/adversarial-review.md](references/adversarial-review.md).
PEP status cannot advance from In Review to Approved without:

1. Files opened during review listed in the PEP (audit trail).
2. Findings written with severity and category.
3. Human explicit approval.

Planning and review are always paired. No exceptions.

If the plan changes structurally after review (a wave is added, files change,
scope shifts), re-run adversarial review. Stale reviews don't grant approval.

## Run Wave

Execute a wave inline in the current session. The wave is not done until the
gate produces real evidence AND that evidence cross-checks against the audit
log.

1. **Pick the wave.** If the user named a number, use it. Otherwise pick the
   first wave with status `[ ]`.
2. **Flip the wave's status to In Progress** by editing the PEP. (For the
   first wave, also flip the PEP status from `Approved` to `In Progress`.)
3. **Do the work** per the wave's primary Shape (see [references/wave-shapes.md](references/wave-shapes.md)).
   For Code (TDD): write failing tests first, present the spec, get human
   approval, then implement. For Refactor: characterise first, then move.
4. **Run each gate command for real** in the shell. Capture exit code and
   output.
5. **Paste evidence into the PEP** under the wave's `Gate Result` subsection.
   See [references/verification.md](references/verification.md) for what
   evidence looks like per shape.
6. **Cross-check against the audit log.** For every command in `Gate Result`,
   grep `.pep/audit.log` to confirm the comm