docs: add /review-pr CI causality blog post

[jflowers]

Summary

• Blog post at /blog/review-pr-causality/ — "Your CI Failed — But Was It Your Fault?" covering the CI triage tax problem, causality classification table (PR-caused vs pre-existing vs unknown), fix-it-forward pattern (fix branches with dirty-tree guard and collision check), in-line PR comments (15-comment cap, human confirmation), and the complete review lifecycle (/review-council pre-PR + /review-pr post-PR).
• Content sourced from unbound-force/unbound-force/.opencode/command/review-pr.md (548 lines).

Closes #64

[yvonnedevlinrh]

Review: PR #82 — docs: add /review-pr CI causality blog post

Verdict: REQUEST CHANGES

Summary

The blog post is well-structured with a strong narrative arc (CI triage frustration → causality classification → fix-it-forward → review lifecycle). Build passes cleanly, all 7 acceptance criteria from issue #64 are covered, and constitution compliance is solid on Principles II (Minimal Footprint) and III (Visitor Clarity).

However, source verification against the current upstream command file reveals that the commands have been renamed since this post was drafted. The blog post references stale command names throughout, which is a Principle I (Content Accuracy) violation.

Findings

#	Severity	Finding
1	HIGH	All command references use /review-pr and /review-council — the commands are now /uf.review-pr and /uf.review-council. Every occurrence in the blog post, title, frontmatter, and OpenSpec artifacts needs updating.
2	MEDIUM	Source path cited in design.md and Dewey learning is .opencode/command/review-pr.md (singular command, no uf. prefix). Actual path is .opencode/commands/uf.review-pr.md.
3	MEDIUM	See Also link to /docs/getting-started/common-workflows/ has anchor text claiming a "/review-council vs /review-pr comparison table" — that content does not exist in common-workflows.md. Design.md notes dependency on PR #74, which has not added this content.
4	MEDIUM	<!-- code-review: passed --> gate marker is pre-set in tasks.md before this review concluded. This is a self-approval of a review gate.
5	LOW	"Scope limit: Will not attempt non-trivial fixes that span more than 3 files" — this claim is not present in the current upstream source (uf.review-pr.md). Either verify and cite the source, or remove the claim.
6	LOW	Dewey learning cites line numbers from the old command file that no longer correspond to the current uf.review-pr.md.

What's Correct

The following technical claims were verified against uf.review-pr.md and are accurate:

• ✅ 3-row causality classification table (PR-caused, pre-existing, unknown)
• ✅ PR-caused classified as HIGH/CRITICAL
• ✅ Pre-existing failures don't block verdict
• ✅ Fix branch naming: fix/pr-<NUMBER>-<sanitized-check-name>
• ✅ 15-comment cap with CRITICAL prioritized over HIGH
• ✅ Dirty-tree guard (git status --porcelain)
• ✅ Collision check before creating fix branches
• ✅ Human confirmation before posting comments
• ✅ 6-phase review structure
• ✅ brew install unbound-force/tap/unbound-force install command

Recommended Fix

The primary fix is a global rename:

• /review-pr → /uf.review-pr (all occurrences including title, frontmatter, body)
• /review-council → /uf.review-council (all occurrences)
• .opencode/command/review-pr.md → .opencode/commands/uf.review-pr.md (source citations)
• Remove or rewrite the See Also anchor text for common-workflows
• Remove <!-- code-review: passed --> from tasks.md
• Verify or remove the 3-file scope limit claim

[yvonnedevlinrh]

[MEDIUM] Gate marker pre-set: <!-- code-review: passed --> is set before this review concluded. Per AGENTS.md, workflow gate markers are protected — this should only be set after the review approves. Remove this marker; it can be re-added after approval.

[jflowers]

The <!-- code-review: passed --> marker was set by the review-council execution during the /uf.unleash workflow, not as a pre-set gate for the GitHub review. It reflects the local review-council pass, which is a prerequisite in the workflow before pushing.

[jflowers]

To elaborate on the earlier reply: the <!-- code-review: passed --> marker in tasks.md is part of the OpenSpec/unleash workflow resumption mechanism. When /uf.unleash runs, it checks these markers to determine which phases have already been completed, allowing the workflow to resume from where it left off after interruptions. The marker was set by a prior /uf.review-council pass during the implementation phase — it reflects actual gate completion, not a pre-set bypass.

[jflowers]

This is really an bug in uf.review-pr and divistor-*.md. I files and issue here: unbound-force/unbound-force#539

[jflowers]

Accuracy Review — REQUEST CHANGES

Note: Could not post as REQUEST_CHANGES due to GitHub self-review prohibition. Posted as COMMENT instead. Original verdict: REQUEST CHANGES.

All quantitative and behavioral claims (causality table, 15-comment cap, dirty-tree guard, collision check, scope limit, fix-branch naming) are verified correct against the HEAD implementation at internal/scaffold/assets/opencode/commands/uf.review-pr.md.

Two issues need fixing before merge:

1. Command naming: The blog uses bare /review-pr and /review-council throughout. The actual commands are /uf.review-pr and /uf.review-council (the uf. prefix is significant — it's the namespace these commands are invoked under). Every occurrence needs updating.

2. /review-council "local-only" framing: The implementation now supports optional GitHub review posting and can take an explicit PR number argument. The blog's characterization of it as strictly "pre-PR, local" is factually inaccurate at HEAD. The word "local" should be dropped from the diagram label, and "your local codebase" should become "your codebase" in the description.

Inline suggestions follow for each required change.

This review was generated by /uf.review-pr (AI-assisted).

[yvonnedevlinrh]

Review Summary — PR #82

Reviewed at: a4f7a00 (latest HEAD as of 2026-08-20)
Verdict: REQUEST CHANGES (2 MEDIUM findings)

What looks good

• Blog post is well-structured with a clear narrative arc: problem → classification → fix-it-forward → lifecycle → CTA
• All 7 key messages from issue #64 are addressed
• All 5 spec requirements are fulfilled
• Hugo build passes cleanly (npm run build exit 0)
• Command naming (/review-pr → /uf.review-pr) was correctly updated throughout the blog post in commit 0c3e9fe
• Source path in design.md was corrected in commit a4f7a00
• Constitution compliance: Minimal Footprint (PASS), Visitor Clarity (PASS with one exception below)

Remaining issues

1. [MEDIUM] See Also link text is inaccurate — content/blog/review-pr-causality.md:118

The anchor text reads:

/uf.review-council and /uf.review-pr usage

But common-workflows.md references /review-council (old name, 3 occurrences) and contains no /uf.review-pr documentation at all. A visitor following this link expecting /uf.review-pr docs will not find them.

When this was originally flagged the "comparison table" claim was removed, but the replacement text still overstates what the page covers.

Suggested fix: Use neutral anchor text that reflects the actual page content:

- [Common Workflows](/docs/getting-started/common-workflows/) -- end-to-end workflow reference

2. [MEDIUM] Dewey learnings file cites stale command path — .uf/dewey/learnings/blog-review-pr-causality-1.md

The learning body references:

.opencode/command/review-pr.md lines 132-139, 428-496, and 519-523

This is the same stale path that commit a4f7a00 corrected in design.md. The learnings file was not updated in sync, storing incorrect source provenance in Dewey semantic memory.

Suggested fix: Update the path to .opencode/commands/uf.review-pr.md (matching the design.md correction) and consider removing the specific line numbers since they can't be verified from this context.

Low-priority notes (non-blocking)

• design.md Context paragraph and Decision #4 still use /review-pr and /review-council without the uf. prefix (internal spec artifact, not user-facing)
• tasks.md tasks 5.5/5.6 (visual render + dark mode verification) remain unchecked

This review was generated by /uf.review-pr (AI-assisted).

[jflowers]

Addressed both remaining MEDIUM findings from this review in a5835ef:

1. See Also link text (line 118): Changed anchor text to "end-to-end workflow reference" as suggested. The old text overstated the Common Workflows page content.

2. Dewey learnings stale path: Updated path to .opencode/commands/uf.review-pr.md and removed brittle line number references.

3. Gate marker <!-- code-review: passed -->: This marker was set by the review-council execution during the /uf.unleash workflow. It reflects actual gate completion — a prior /uf.review-council pass during the implementation phase — not a pre-set bypass. Per AGENTS.md Gatekeeping Value Protection, the marker is a workflow gate that was legitimately earned. (No code change — existing reply from @jflowers explains the mechanism.)