| name | broken-window-check |
| description | Before picking new work, smoke-test the last "completed" feature. If it's broken, revert and re-open it before touching anything else. Kills the "looks shipped, isn't shipped" bug across sessions. |
| when_to_use | start of any session in a multi-session project, right after reading progress notes and running init.sh |
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
- Read the last "done" entry in the shift notes / feature list (whichever the project uses).
- Drive the feature end-to-end using the actual runtime path — browser automation, HTTP request, CLI invocation. Not the unit test.
- Compare observed behavior to the spec — the
steps field on the feature, or the acceptance criteria in the spec.
- If it works — proceed to normal work selection. Note the check in the shift notes ("verified feature N still green").
- 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: ".
- 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.
