docs(stories): add story 09 — standing audit loops in practice#73
Merged
Conversation
Story 08 introduces standing audit loops alongside `**Blocked**`, `**Research**`, `**Last-enriched**`, `**Parent**`, and policies, but only describes the pattern in passing — readers had no worked walkthrough to model their own usage on. Add story 09 with one full cycle, mirroring the Try-it-yourself shape PR #60 established for every other story. Sections: 1. **When to reach for one** — recurring queue refill, scheduled audit cadence, post-deploy checklist, onboarding-friendly audits. 2. **The shape** — canonical TASKS.md block with `**Tags**: standing-loop, audit, queue` + the `standing-audit-gap-loop` ID. 3. **How agents pick it up** — `pickBestTask` skips `standing-loop` tasks during automatic walks; `/next-task standing-audit-gap-loop` targets it on demand. Cross-references the parser, CLI, and MCP tests that pin the contract. 4. **The agent's audit pass** — five-step rule lifted from `spec.md`, with a sample commit message that closes the loop. 5. **Anti-pattern** — don't promote every recurring task to a standing loop. Symptoms + the "one loop per repo" rule of thumb. The runnable demo creates a temp directory, drops one normal task and one standing-loop task into TASKS.md, and shows `tasks pick` returning `Candidates: 1` (the standing-loop task is filtered out) while `tasks list --priority P2` returns both rows. Demo executed locally and the expected highlights match what `tasks pick` actually prints. Cross-links: - `docs/user-stories/README.md` table — new row 9. - `docs/user-stories/08-rich-task-metadata.md` — closing line of the Standing Audit Loops section now points to story 09 for the worked example. - `spec.md` standing-audit-loops section — adds the one-line "See User Story 09 for a worked example" cross-link the task asked for, no other spec changes. Verification: `npm run build`, `npm test` (415/415), `npm run lint`, `npx -y @tasks-md/lint TASKS.md` all pass; the runnable demo was executed end-to-end and produced the documented output. closes user-stories-09-standing-loops-walkthrough
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why needed
Story 08 lists standing audit loops alongside the rest of the rich-metadata fields, but only sketches the pattern — readers had no full walkthrough to model their own usage on. Story 09 closes that gap with one complete cycle: when to reach for the pattern, the canonical TASKS.md shape, how
pickBestTaskand/next-taskhandle it, the audit pass itself, and the anti-pattern to avoid. Closinguser-stories-09-standing-loops-walkthrough.What changed
docs/user-stories/09-standing-audit-loops.mdwith the five sections required by the task brief (When to reach for one, The shape, How agents pick it up, The agent's audit pass, Anti-pattern: don't over-loop) plus the## Try it yourselfdemo that PR docs: add Try-it-yourself runnable demo to every user story #60 established as the template for every story.docs/user-stories/README.md— new row 9 in the user-stories index table, between row 8 and the Automation Status section.docs/user-stories/08-rich-task-metadata.md— closing line of the Standing Audit Loops section now points readers to story 09 for the worked example.spec.md— adds the one-line "See User Story 09 for a worked example" cross-link the task brief asked for, with no other spec changes.Runnable demo
The Try-it-yourself block creates a tmp directory, drops one normal task plus one
standing-loop-tagged task into TASKS.md, and shows the contract:Candidates: 1is the proof — the queue has two checkbox tasks, butpickBestTaskfiltered out the standing-loop one.tasks list --priority P2then shows both rows (sincelistenumerates without skipping). I ran the demo end-to-end before committing; the output matches what the doc claims.Acceptance check
docs/user-stories/README.mdtable has the new row in the right priority (07 → 08 → 09).spec.mdstanding-loops section gets the one-line "see story 09 for a worked example" link.npm run build— passes.npm test— 415/415 (cli 183, lint 43, mcp 111, parser 78).npm run lint—Checked 1 file(s), found 0 error(s).npx -y @tasks-md/lint TASKS.md—Checked 1 file(s), found 0 error(s).closes user-stories-09-standing-loops-walkthrough
🤖 Written by an agent, not Fyodor. Ping me if this looks off.