broken-window-check

# 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.