broken-window-check

Files (1)

• SKILL.md

SKILL.md (first lines)

# Broken-Window Check

Across shift-notes-driven sessions (see `shift-notes`), agents will sometimes mark a feature complete after unit tests pass — even when the feature is end-to-end broken. The next session opens the repo, sees a green git log, and builds on top of a broken foundation. By the time anyone notices, three features are stacked on the crack.

**The check:** before picking new work, exercise the most recently "completed" feature end-to-end. If it fails, treat it as your only job this session.

## The sequence — run in order, no skipping

1. **Read the last "done" entry** in the shift notes / feature list (whichever the project uses).
2. **Drive the feature end-to-end** using the actual runtime path — browser automation, HTTP request, CLI invocation. Not the unit test.
3. **Compare observed behavior to the spec** — the `steps` field on the feature, or the acceptance criteria in the spec.
4. **If it works** — proceed to normal work selection. Note the check in the shift notes ("verified feature N still green").
5. **If it fails** —
   - `git revert` the commit that claimed completion (do not force-push).
   - Set that feature's status back to `not-done` in the feature list.
   - Note in shift notes: "reverted feature N, cause: <one line>".
   - Fix it. That is your entire session.

Do not pick new work on top of a broken previous feature. Ever.

## What "end-to-end" means

The check must exercise the path the user actually takes. Anything less is theater.

| Feature shape | Valid check | Invalid check |
|---|---|---|
| Web UI button | Puppeteer/Playwright click → observe DOM | `expect(handler).toHaveBeenCalled()` |
| HTTP endpoint | `curl` the route → check status + body | Unit test on the handler function |
| CLI flag | Invoke the binary with the flag → observe output | Import the parser, assert on the AST |
| Background job | Trigger it → wait → assert side effect | Assert the job function returns |

## Red flags — the check is not doing its job

- **You're reading tests instead of running the feature.** Tests can pass while the feature is broken (wrong route, missing CORS, config mismatch). Drive the runtime.
- **You add a mock to make the check pass.** The mock is the bug. Remove it, watch the failure, that's the real state.
- **You "fix" by editing the feature list to match reality** ("oh it never supported X"). No. Revert. Re-open. Fix the code or negotiate scope in the spec, not the ledger.
- **You skip the check because "it worked yesterday".** Yesterday's session doesn't run today's dev server.

## Cost

The check is 30-90 seconds per session in a healthy project. In a project that's about to go sideways, it saves hours. The dropout in premature-completion rate is roughly 4x when the check is enforced vs. not (measured in shift-work-style agent runs).

## Pairs with

- `shift-notes` — the ledger the check reads and writes.
- `adversarial-verify` — run this on the current session's diff *before* claiming done, so the next session doesn't have to broken-window you.
- `verification-before-completion` — the general form of "don't claim without evidence".

If every session enforces the check, the compounding-error mode of shift-work agents stops compounding.

From Archive228/loopkit, MIT.

More from Archive228/loopkit