.agents/skills/sprint-delivery/SKILL.md

Ref: main   Size: 7.3 KiB   History

---
name: sprint-delivery
description: Deliver one working slice of git-collab at a time, with opening and closing cleanup, adversarial review, real-boundary validation, a demonstrable result, and a durable retrospective with checkable actions. Use when the user asks for sprint delivery; ordinary isolated edits do not need it.
---

# Sprint delivery

Deliver one useful, working slice at a time. Keep session continuity in the
repository, not in the conversation. This skill supplies a workflow; it does
not authorize a new sprint, a deployment, or publishing anything.

Adapted for git-collab from the maintained copy in `~/code/rad/mux`
(`docs/skills/sprint-delivery/SKILL.md`), which has closed 49 retrospective
actions this way. Differences from that copy are noted where they matter.

## Use with any agent

This file is ordinary Markdown; a skill loader is optional. For tools without
automatic discovery, ask: "Read `.agents/skills/sprint-delivery/SKILL.md` and
use it to resume the sprint." `AGENTS.md` points here and at `CLAUDE.md`.

Do not restate rules that live in `CLAUDE.md` — invariants, working rules,
gates, and the context-hazard list are there, and one rule per question is
itself an invariant. Read it first; this file is the procedure, that file is
the law.

## Resume from evidence

Read `CLAUDE.md`, `git status`, recent commits, the current spec/plan, and
**the open actions and retained debt in `RETRO.md`** — that file is an input,
not a diary. Read relevant sections rather than full history; the repo is
large and every token is re-billed each turn.

Report what is implemented, validated, accepted, and still open as **distinct
facts**. A green suite is not user acceptance; say what was verified and what
was only asserted.

## Run a bounded sprint

1. **Scope and acceptance.** Choose the smallest functional deliverable within
   the authorized plan. Define observable acceptance scenarios. Carry forward
   applicable `RETRO.md` actions, and honour any debt whose *trigger* this
   slice fires. Clarify material unknowns early; continue independent work
   while waiting.
2. **Opening cleanup.** Inspect the touched code for small refactors that help
   the slice; commit them separately. If the code is ready, say so — there is
   no cleanup quota.
3. **Implement with adversarial review.** See the pairing below. Deliver
   through real user interactions and system boundaries, not through unit
   tests alone.
4. **Closing cleanup.** Explicitly review duplication, obsolete paths,
   temporary scaffolding, and unnecessary state. Refactor what the slice
   exposed — a second predicate for a question the codebase already answers is
   the specific thing to look for. Record retained debt with its location,
   consequence, and **next owner or trigger**.
5. **Validate and demonstrate.** Run the gates, then verify real behaviour
   beyond your own agreement. Freeze the source before final checks and rerun
   affected ones after any change. Demonstrate the result, including its
   failure paths.
6. **Close and hand off.** Commit validated work. Update the spec/plan status
   and `RETRO.md`: what was delivered, what worked, lessons, retained debt, and
   **checkable actions for the next slice**. Promote anything that generalises
   into `CLAUDE.md` — `RETRO.md` is not read at decision time, `CLAUDE.md` is.
   Record demo acceptance only when it is given.

## Plans state invariants, not just steps

A plan in `docs/superpowers/plans/` is a hypothesis, not an authority. The only
bug in the lease slice came from a plan step that was implemented faithfully
(2026-09-06: it said delete the row, which resets the fencing counter). So:

- Write the **invariant** beside the steps that must preserve it, and check new
  steps against `CLAUDE.md`'s invariants section.
- A step that contradicts an invariant is a **bug in the plan**, to be fixed in
  the plan document — not worked around in the code.
- Before writing the happy path, enumerate the **boundary members**: empty,
  single, first/root, duplicate or already-seen, freed-then-reused. Five
  file-history bugs and one lease bug were all this one shape.

## Pairing and review

**Independent review is the goal; sequential self-review is the fallback.**
Where subagents are available, use one economical implementer and one capable
adversarial reviewer, give each the deliverable, file paths, edit ownership,
constraints, acceptance checks, and its partner's name, and have the reviewer
send concrete findings — trigger, consequence, expected behaviour — directly to
the implementer. Re-review changed parts, not the whole slice, each round.

Where they are not available (the common case in this repo today), implement
and then make a **separate, deliberately hostile review pass** over the diff,
and **disclose that the review was not independent**. Do not claim a check ran
that did not. Keep the same acceptance scenarios, gates, demo, and
retrospective either way.

Escalate a specific hard problem to a stronger model when justified; do not
silently inherit an expensive one.

## Validation that answers the claim

Gates: `make lint` before a commit, `make ci` before delivery,
`cargo clippy --all-targets` silent. **The baseline is not green** — see
`CLAUDE.md`'s Gates section for the ten known failures and why. Consequences
for this workflow:

- `cargo test --no-fail-fast` is the only way to see every target.
- A new failure must be told apart from those ten **by name**, and named in the
  report. "Same as before" is not a verification.
- Never answer "did I break this?" by touching the index or HEAD. Use
  `git worktree add --detach /tmp/base-check <ref>`.

Ask the outside about the inside — a component reporting on itself cannot catch
itself being wrong. In this repo that means:

- Keys come from `ssh-keygen`, never our own encoder; SSH behaviour is asserted
  through the real `ssh` client, and git behaviour through real `git`.
- Server work goes through `tests/common/mod.rs::ServerHarness`, which runs a
  real `git-collab-server` subprocess. A claim about two principals racing
  needs two authorized keys, not one key twice.
- `--json` output is the machine-checkable oracle; assert on it rather than on
  prose. Prose abbreviates ids, JSON does not.
- Capture `$?` before piping: `cargo test | grep -c ok` reports grep's status.

## Demonstrating a CLI and a web UI

git-collab has no GUI to record, so a demo is:

- **Transcripts** of the real binaries doing the real thing, including the
  failure paths — a refused claim and a lost race, not only the happy one.
- **Rendered pages** from a live server for anything the web UI shows.
- **`README.md` checked against reality.** It is where a claim about the CLI's
  output gets verified; writing the section is how the un-abbreviated lease ids
  were caught. If the README and the binary disagree, one of them is a bug.

Do not quote a performance number measured in a debug build.

## Repository hygiene

- **Branch before the first commit of a slice.** Committing onto the base
  branch renders an empty diff in Delta's Changes view while the work piles up
  invisibly.
- **Stage by path, never `git add -A`.**
- Commit messages are plain imperative ("Enforce one review vote per author per
  revision"). Keep each task's commit separate; the history should tell the
  feature's story.
- Do not embed current phase numbers, commit ids, or temporary URLs in this
  skill.