Ship the §5 companion files, the deferred template sync, and 0.6.0 - #14
Conversation
Three findings came out of a real project running this workflow. This is the second of two PRs; #13 took the mechanical checks. Finding A was cut after five Gate-A passes and finding B after two — both are stories now, carrying the findings that killed them as their opening evidence. **Companions (finding C).** The §5 protocol knew only about the findings file, so dispositions and interrupted-cycle state lived in chat history and died with the session. Both §5 copies now describe two advisory companions: a per-pass dispositions file, and a cycle-stable resume note — gate-a-spec-resume.md, gate-a-plan-resume.md, gate-b-resume.md. Cycle-stable rather than pass-named because a note keyed to the interrupted pass is exactly the file a resuming agent will not look for once the counter moves. Gate B gets one note even under reviewType: full: the per-branch findings files race only because Codex's two reviewers write them, while the resume note is written by the outer agent, sequentially. Both are optional and nothing enforces them — the ledger row says so rather than implying P std made context durable. **Template sync.** The ad-hoc-briefs paragraph, deferred since #12, is now in the scaffolded template — but not verbatim. The repo paragraph links a file /workflow-init never scaffolds and asserts this repo's own incident count, so downstream gets a neutral variant preserving both halves of the principle: briefs carry the checklist's habits, and nobody reviews a brief against all 12 items. The canvas provenance line stays repo-only, per prompt-standards item 8. **Bot completion signal.** #12 and #13 both merged heads that were never reviewed: the check passed while the comment read "Review rate limited", and on #13 the only CodeRabbit review record names eed589c while the merged head was 92de0d2. docs/pr-review-bots.md now separates "the check stopped pending" from "the head was reviewed" across all three sites, with a verification command that was found broken by running it — gh api --slurp is rejected with --jq — and is now measured in both directions. Gate A: 8 passes, clean. Gate B: 5 passes, final spec and quality both clean on an unchanged tree.
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
Warning Review limit reached
Next review available in: 15 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe PR documents optional findings companions and ad-hoc prompt guidance, expands CodeRabbit review verification instructions, adds a hardening taxonomy and ledger entry, updates follow-up records, and bumps the plugin version to 0.6.0. ChangesWorkflow hardening and release
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThis PR releases dev-workflow 0.6.0 with documentation and scaffold updates.
Confidence Score: 5/5The PR appears safe to merge, with no concrete changed-code failure identified. The two prompt copies remain aligned, companion artifacts stay explicitly optional and outside pass validation, the live-head review command has coherent pagination and exit-status behavior, and the release metadata describes the shipped scope consistently. Important Files Changed
Reviews (1): Last reviewed commit: "Ship the §5 companion files, the deferre..." | Re-trigger Greptile |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/pr-review-bots.md`:
- Around line 41-49: Update the merge-gate command example around the
`gh`/`jq`/`grep` pipeline to avoid relying on unpinned runtime tools: either
remove the shell example or document and invoke a repository-pinned or
runtime-locked toolchain provisioned for this check. Ensure the documented
command uses that locked tooling for the review filtering logic.
In `@todos.md`:
- Around line 134-141: Make the P2 + P6 entry in the todos.md work queue
consistent: either remove the “FIRED” trigger state and leave the unchecked item
pending, or check/move it into an active queue state with a concrete next
action. Ensure it no longer simultaneously indicates that the trigger fired and
that implementation has not started.
- Around line 232-240: Update the process-pr-review step reference in the
“Finding A” entry to use step 5, matching the mandated ledger-check step and the
rest of the story; leave the surrounding scope and behavior text unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d67e9166-ffeb-4e95-9064-bc992a0c13b6
📒 Files selected for processing (9)
CLAUDE.mddocs/hardening-log.mddocs/hardening-taxonomy.mddocs/pr-review-bots.mddocs/superpowers/plans/2026-07-26-cycle-close-nudge-and-companions.mdplugins/dev-workflow/.claude-plugin/plugin.jsonplugins/dev-workflow/CHANGELOG.mdplugins/dev-workflow/commands/workflow-init.mdtodos.md
| ```sh | ||
| head=$(gh pr view <n> --json headRefOid --jq .headRefOid) # the LIVE head, not local HEAD | ||
| gh api --paginate repos/<owner>/<repo>/pulls/<n>/reviews | jq -s " | ||
| [ .[][] | ||
| | select(.user.login==\"coderabbitai[bot]\") | ||
| | select(.commit_id==\"$head\") | ||
| | select((.body // \"\") | test(\"rate limit\"; \"i\") | not) | ||
| | select(.state==\"COMMENTED\" or .state==\"APPROVED\" or .state==\"CHANGES_REQUESTED\") | ||
| ] | length" | grep -qv '^0$' |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "File excerpt:"
sed -n '1,90p' docs/pr-review-bots.md | cat -n
echo
echo "Search for exact tool usage in docs/pr-review-bots.md:"
rg -n '\b(gh|jq|grep)\b' docs/pr-review-bots.md || true
echo
echo "Search pinning examples in docs/scripts:"
git ls-files '*.{md,sh,json,yml,yaml}' | xargs rg -n '\b(gh|jq|grep)\b' | head -200Repository: dsnger/dev-workflow-kit
Length of output: 40198
🌐 Web query:
docs/prompt-standards.md CodeRabbit checks required
💡 Result:
There is no standard requirement or built-in check named docs/prompt-standards.md in CodeRabbit [1][2]. CodeRabbit employs a system of "Code Guidelines" to enforce coding standards, which automatically detects and applies existing configuration files used by other AI agents [3][4]. The default list of files monitored for these guidelines includes [1]: -.cursorrules -.github/copilot-instructions.md - CLAUDE.md - GEMINI.md -.cursor/rules/ -.windsurfrules -.clinerules/ -.rules/* - AGENT.md - AGENTS.md - REVIEW.md If you have your coding standards stored in a file named docs/prompt-standards.md, CodeRabbit will not detect it automatically by default [1][3]. To use this file, you must explicitly add it to your configuration in your .coderabbit.yaml file using the knowledge_base.code_guidelines.filePatterns setting [3]: yaml knowledge_base: code_guidelines: filePatterns: - "docs/prompt-standards.md" Once configured, CodeRabbit will pick up the rules defined in that file and apply them as review criteria [3][4]. Note that adding guideline files to path_instructions is incorrect, as that treats the file as source code to be reviewed rather than as a source of rules [3].
Citations:
- 1: https://docs.coderabbit.ai/reference/configuration
- 2: https://docs.coderabbit.ai/pr-reviews/pre-merge-checks
- 3: https://docs.coderabbit.ai/knowledge-base/code-guidelines
- 4: https://www.coderabbit.ai/blog/code-guidelines-bring-your-coding-rules-to-coderabbit
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Find prompt-standards:"
git ls-files | rg '(^|/)docs/prompt-standards\.md$|prompt-standards' || true
if [ -f docs/prompt-standards.md ]; then
echo
echo "First 220 lines of docs/prompt-standards.md:"
sed -n '1,220p' docs/prompt-standards.md | cat -n
fi
echo
echo "Determine whether docs/pr-review-bots.md is a skill/command/agent/hook message/scaffold:"
git ls-files | rg '^plugins/dev-workflow/(skills|commands|hooks|.*templates.*)|(^|/)\.mcp\.json$|(^|/)docs/prompt-standards\.md$|(^|/)AGENTS\.md$' | sed -n '1,220p'Repository: dsnger/dev-workflow-kit
Length of output: 10748
Pin or avoid unpinned runtime tools in the merge-gate command.
docs/pr-review-bots.md is Markdown, but the documented pipeline still depends on unsigned/pinned tool versions (gh, jq, grep). Treat this as documented executable tooling: either remove the shell example or document where a repository-pinned/runtime-locked toolchain is provisioned and use it for the merge-gate check.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pr-review-bots.md` around lines 41 - 49, Update the merge-gate command
example around the `gh`/`jq`/`grep` pipeline to avoid relying on unpinned
runtime tools: either remove the shell example or document and invoke a
repository-pinned or runtime-locked toolchain provisioned for this check. Ensure
the documented command uses that locked tooling for the review filtering logic.
Source: Coding guidelines
| - [ ] **P2 + P6 — risk/security profiles, and security sections in the intake, spec and | ||
| gate templates.** One story: the profile is what the sections key off, so shipping | ||
| the sections without it just adds a heading nobody knows how to fill in. | ||
| *Trigger: the first real intake in a product project* — the first time a story | ||
| exists whose risk profile is a real answer rather than a guess about what product | ||
| projects might need. | ||
| *Trigger: the first real intake in a product project* — **FIRED.** | ||
| Calibration point (infinite-portfolio-canvas, 2026-07-26): 51 Gate-A pass files | ||
| across 2 stories — spec 14, plan 14, replan 4, amend 12, a3-spec 7 — in a product | ||
| project on a long-lived branch. That is a real risk profile to key sections off, | ||
| not a guess about what product projects might need. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Keep the trigger state consistent with the work queue.
Line 137 marks P2 + P6 as FIRED, but the item remains unchecked under ## Next while the plan explicitly says it is not implemented and nothing belongs under ## Now. Either leave the trigger pending until work is pulled, or move it to an active state with a next action; do not record both “fired” and “not started.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@todos.md` around lines 134 - 141, Make the P2 + P6 entry in the todos.md work
queue consistent: either remove the “FIRED” trigger state and leave the
unchecked item pending, or check/move it into an active queue state with a
concrete next action. Ensure it no longer simultaneously indicates that the
trigger fired and that implementation has not started.
Source: Coding guidelines
CodeRabbit on #14: the parked Finding A entry said the mandated ledger check lives in `process-pr-review` step 4. It is step 5 — step 4 is the stop-and-ask-the-user step. Verified against the command itself, which this PR does not modify. Validated by hand rather than by subagent: #14 touches CLAUDE.md and plugins/, so process-pr-review's instruction-path precheck bars triage. Left alone deliberately: docs/superpowers/specs/2026-07-18-... also says step 4. That is a historical artifact recording what was true when written, this PR does not touch it, and docs/superpowers/ is excluded from the conformance checks for exactly that reason. Gate B triviality skip, documented per CLAUDE.md §5: a one-word correction to a backlog entry, no behaviour and no mechanism changed.
|
Processed — three tracked claims: one accepted and fixed, two dismissed. This PR touches 1.
|
|
@coderabbitai review |
✅ Action performedReview finished.
|
#12 and #13 merged unreviewed heads and the miss was found afterwards. On #14 the verification query caught it BEFORE merging: check green, comment rate-limited, zero qualifying reviews for the head. Re-trigger produced nothing; merged on an explicit human decision with the exception recorded. Gate B triviality skip, documented per CLAUDE.md §5: prose-only addition to a descriptive table's surrounding notes, no mechanism or routing changed.
Merge exception — recorded before mergingMerging with head unreviewed, on an explicit human decision, per the bounded
What is unreviewed: a one-word prose correction CodeRabbit itself requested This is the fourth observation of the pattern and the first caught before a Round report — canvas field findingsFour findings from a real project running this workflow. Two shipped, two were
Both cuts followed the same signal: sustained review fire on one paragraph means Gate totals. #13: Gate A 9 passes, Gate B 8 passes, 13 defects. #14: Gate A 8 What review could not catch. The verification command in this PR could not Left open, deliberately: |
Documents that CodeRabbit's "Review rate limited" message carries no information in either direction — it appears on heads that were never reviewed and on heads that were — so the per-head review count is the only arbiter. MERGED AS AN EXPLICIT HUMAN EXCEPTION — head c62455b went unreviewed by CodeRabbit. Per-head verification ran twice against c62455b and returned 0 both times: before the re-trigger, and after `@coderabbitai review` plus a ~5 minute wait. Zero CodeRabbit review records exist on this PR for any head. Its status check was green throughout. CodeRabbit's own comments: at 12:13Z "Review limit reached — you've reached your PR review limit, so we couldn't start this review"; after the re-trigger, "Review finished… does not re-review already reviewed commits" with no review record produced. The re-trigger cannot recover this head. Decision by Daniel, following the #14 precedent. The change is docs-only (docs/pr-review-bots.md, no other path) and Greptile reviewed it — check green.
The count rule carried two facts fused into one sentence. They separate: 1. The per-head count is the arbiter of whether a head was reviewed — unchanged, and the diagnostic for any bot. Routing a bot opportunistically does not make its review record less readable or the answer less true. 2. "Merge only on an explicit recorded human decision" binds only bots under Wait for. An absent review from an opportunistic bot blocks nothing and needs no exception: every head reaching a PR has already passed Gate B, the workflow's actual cross-model review, and the PR bots are a supplementary third instance. Requiring a recorded exception whenever a supplementary reviewer stayed quiet would reimpose as ceremony the blocking that opportunistic routing removed. The clause is dormant, not retired — Wait for is empty, so nothing triggers it; promote a bot back and it reactivates unchanged for that bot. The #12–#18 history and the #14 precedent stay as the record of when it was live: a real requirement under the routing of its time. Four sentences elsewhere attached a merge consequence to a `0` and are corrected to state the routing dependency: the scope paragraph above the completion-signal list, the "decides whether you may merge" bullet, "`0` means do not merge", and the "run it on every merge" lead-in to the query. Gate B: N/A — the only staged path is explanatory documentation (docs/pr-review-bots.md) per §5's prose rule. Battery green: shellcheck (6 files), hook tests, invariant tests + check (123 assertions), version-bump tests + check (36 assertions), `claude plugin validate . --strict`.
Docs-only, two files, no plugin path — no version bump. CodeRabbit leaves Wait for after five consecutive unreviewed heads (#12, #13, #15, #16, #17 — the last with zero review records on the PR) followed by a genuine review on #18. Real findings source, unpredictable delivery, and a completion signal that fires regardless of whether a review happened: the opportunistic category by this file's own definition. Wait for is now empty. Row additions: the status check goes green whether or not a review happened, and `@coderabbitai review` is a no-op while automatic reviews are active (CodeRabbit's own message on #17), which retroactively explains #14's "re-trigger produced nothing". Plan corrected to Free; "Pro Plus" was observed on PR #1 only. The count rule's two facts separated: the per-head count remains the arbiter of whether a head was reviewed, for any bot; the recorded-human-decision requirement binds only bots under Wait for, and is dormant while that list is empty. Every head reaching a PR has already passed Gate B, so a quiet supplementary reviewer needs no exception. MANIFEST.md: the bare `CLAUDE.md` row resolved to the repo root and produced a false Major on #18. Qualified to source-files/CLAUDE.md, with the three files distinguished, and root §6 (context canary) recorded as deliberately outside the §1–§5 template range and never to be synced into the scaffolded template. Pre-merge diagnostic: per-head count 1 on head 2634bf2 — reviewed. One Minor finding (drop or explicitly optionalize the re-trigger step) collected, not actioned, per §5's Minor/Nit rule. Gate B: N/A — every path is explanatory documentation per §5's prose rule. Battery green at each commit.
Resolves the Minor collected on #19. The file established that `@coderabbitai review` is a no-op while automatic reviews are active, then instructed operators to run it anyway inside the deterministic merge verification — described twice, once imperatively and once undercut. The imperative is out; the procedure ends at the DISMISSED filter and the step survives once, as an explicitly optional note beside the human-exception clause it precedes, which also scopes it to Wait-for bots. Facts kept: the no-op behaviour with its #17 source, that #14 and #17 both produced nothing, that nothing claims a re-trigger cannot work (only that this account has never seen one work), and that `full review` must not be claimed effective without a run observed here. Pre-merge diagnostic: per-head count 0 on head 55c3d74 — which blocks nothing, Wait for being empty. Recorded on the PR: this 0 is a false negative. CodeRabbit reported "No actionable comments were generated in the recent review" over 286c55f..55c3d74, so the head was reviewed and simply had nothing to say; a zero-finding review posts no review record. The count conflates "not reviewed" with "reviewed, clean". Follow-up, not fixed here. Gate B: N/A — single explanatory documentation path per §5's prose rule. Battery green before commit.
1 participant
PR 2 of the canvas field-findings round. #13 took the mechanical checks; this takes the prompt-text changes and the release.
Two of the four findings were cut rather than shipped, and that is the main
result of this round. Finding A (a route from a fixed finding to the ledger for
projects that never open PRs) drew a Major on all five Gate-A passes; finding B
(a §5 version stamp) on two. Both are now stories in
todos.md, opening withthe findings that killed them rather than a restatement of intent.
What ships
<slot>-dispositions.mdand a cycle-stable resume note, in both §5 copiessession-bound-context-not-durabletodos.mdpr-review-bots.mdWhy the resume note is cycle-stable, not pass-named: a note keyed to the
interrupted pass is exactly the file a resuming agent will not look for once the
counter moves or an incomplete pass is discounted. Gate B gets one note even
under
reviewType: full— the per-branch findings files race only becauseCodex's two reviewers write them concurrently, while the resume note is written
by the outer agent, sequentially.
Why the template sync is not verbatim: the repo paragraph links
docs/sparring-briefing.md, which/workflow-initnever scaffolds, and assertsthis repo's own incident count. Downstream gets a neutral variant preserving
both halves of the principle — briefs carry the checklist's habits, and
nobody reviews a brief against all 12 items. Dropping the second half would
invent a process nobody runs.
The ledger row states that nothing enforces the companions. They are
optional notes;
P stddoes not make context durable, it recommends durablenotes. A row implying otherwise would be
unverified-enforcement-claim— theclass resolved at rung 2 in #13, one PR ago.
The bot caveat, and how it was found
#12 and #13 both merged heads that were never reviewed. The check passed
while the comment read "Review rate limited"; on #13 the only CodeRabbit review
record names
eed589cwhile the merged head was92de0d2.docs/pr-review-bots.mdnow separates "the check stopped pending" (theblocking signal) from "the final head was reviewed" (a separate verification),
across the table row, the Wait-for entry and the completion-signal paragraph.
The verification command took three passes, and each defect needed a different
method:
gh api --slurpis rejected with--jq— the command could not run--slurpafter the fixjqstage while the pipeline ends ingrep -qvA quality pass had reviewed that file clean, under instruction to check the
pipeline, while the unrunnable command was in it. That is why AGENTS.md carries
"never document a command that wasn't run" as a rule rather than a review
expectation. The command is now measured in both directions: the
jqstageprints
0for the merged head and1for the reviewed commit; the fullpipeline exits
1and0, inverted so exit 0 means "a qualifying reviewexists" and it can gate a merge.
Review
Gate A: 8 passes, clean (8 → 8 → 7 → 9 → 5 → 5 → 3 → 0; the drop is where A was
cut). Gate B: 5 passes, final spec and quality both clean on an unchanged tree.
Invariant-11 self-review run over both changed prompt texts.
workflow-init.mdstill carries exactly one column-zeroTarget model:lineand a checklist agreeing with the repo copy at 12 — verified after each edit,
since #13's checks are live on main and police the file this PR edits.
Summary by CodeRabbit
New Features
Documentation
Release