Skip to content

docs(stories): add story 09 — standing audit loops in practice#73

Merged
fyodoriv merged 1 commit into
mainfrom
docs/story-09-standing-loops-walkthrough
May 3, 2026
Merged

docs(stories): add story 09 — standing audit loops in practice#73
fyodoriv merged 1 commit into
mainfrom
docs/story-09-standing-loops-walkthrough

Conversation

@fyodoriv
Copy link
Copy Markdown
Collaborator

@fyodoriv fyodoriv commented May 3, 2026

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 pickBestTask and /next-task handle it, the audit pass itself, and the anti-pattern to avoid. Closing user-stories-09-standing-loops-walkthrough.

What changed

  • New docs/user-stories/09-standing-audit-loops.md with 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 yourself demo 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:

Picked "Document the new pagination flag" (P2)
  Candidates: 1

Candidates: 1 is the proof — the queue has two checkbox tasks, but pickBestTask filtered out the standing-loop one. tasks list --priority P2 then shows both rows (since list enumerates without skipping). I ran the demo end-to-end before committing; the output matches what the doc claims.

Acceptance check

  • New story 09 exists with the 5 sections + a Try-it-yourself demo.
  • docs/user-stories/README.md table has the new row in the right priority (07 → 08 → 09).
  • spec.md standing-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 lintChecked 1 file(s), found 0 error(s).
  • npx -y @tasks-md/lint TASKS.mdChecked 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.

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
@fyodoriv fyodoriv merged commit 035ec34 into main May 3, 2026
4 checks passed
@fyodoriv fyodoriv deleted the docs/story-09-standing-loops-walkthrough branch May 3, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant