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.