feat(clairvoyance): code-review charter + operator skills - #538
Merged
Conversation
A cold-agent baseline confirmed the failure this closes: asked to review a reducer diff before merge, an agent with no project skill reviewed code-first and convention-blind, applied only generic Rust dimensions, consulted none of the ADRs, checklist, or reviewer charters, and issued a merge verdict on its own authority. The code-review charter makes the review contract canonical in .Clairvoyance/staff/: a load order that starts at the routing indexes, a three-layer recipe (contract conformance, adversarial false-story pass, then the generic mechanical pass explicitly subordinate), a verification rule that the code wins over any summary, and a report shape whose verdict is named gate states (CI, CodeRabbit approved_at_head, contract conformance) with merging stated as the owner's action outside any review. library.md routes every review to it. Two thin Claude Code skills make the structure invokable by the operator: cmtraceopen-code-review (the charter runner) and cmtraceopen-agent (the soul.md/memory.md specialist loader). Hermes-side thin wrappers exist at ~/.hermes/skills/software-development/ pointing at the same canonical files. Verified by dry-run scenario agents: the baseline (RED) failures above, and a GREEN run that followed the full document chain in order, applied the layers correctly, produced the gate-state report without a merge verdict, and routed the ADR-004 redaction ambiguity to the Reducer Contract Agent instead of adjudicating locally. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe changes add cmtraceopen review routing, a repository-specific review charter, and Claude skills that load canonical guidance and produce gate-state review reports. Changescmtraceopen review guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 @.Clairvoyance/staff/code-review-charter.md:
- Line 22: Update the charter links at the referenced entries in the staff
charter document to use repository-qualified paths under .Clairvoyance/staff/,
matching the path style used by .Clairvoyance/library.md for both
reducer-contract-charter.md and the other linked charter.
- Around line 27-35: Update the review-layer requirements in the charter so the
Contract and Adversarial layers apply conditionally to reducer or evidence-lane
changes, while UI, packaging, documentation, and skill changes use
repository-wide review inputs instead. Ensure non-reducer reviews are not
required to answer reducer-specific checklist questions without applicable
contract or adversarial sources.
🪄 Autofix
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: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5ee32e86-7373-4d4e-b46f-356f4a675942
📒 Files selected for processing (4)
.Clairvoyance/library.md.Clairvoyance/staff/code-review-charter.md.claude/skills/cmtraceopen-agent/SKILL.md.claude/skills/cmtraceopen-code-review/SKILL.md
| (`crates/cmtraceopen-parser/src/intune/`, `src/sccm/`): the four ADRs in | ||
| `docs/architecture/decisions/`, the reducer review checklist in | ||
| `docs/superpowers/plans/2026-08-07-reducer-framework-v1.md`, and the | ||
| [[reducer-contract-charter.md]] hard rules. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use fully qualified paths for the staff charters.
The links at Lines 22 and 33 use bare filenames. .Clairvoyance/library.md uses .Clairvoyance/staff/... for these same charters. A reviewer can fail to load the contract and adversarial guidance. Use the repository-qualified paths.
Also applies to: 33-33
🤖 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 @.Clairvoyance/staff/code-review-charter.md at line 22, Update the charter
links at the referenced entries in the staff charter document to use
repository-qualified paths under .Clairvoyance/staff/, matching the path style
used by .Clairvoyance/library.md for both reducer-contract-charter.md and the
other linked charter.
Comment on lines
+27
to
+35
| A complete review has three layers, in order: | ||
|
|
||
| 1. **Contract layer** — conformance to the ADRs and the reducer review checklist: | ||
| evidence strength vs confidence, identity/correlation strength, chronology and | ||
| terminal precedence, coverage honesty, redaction scope. Every checklist question | ||
| gets an answer grounded in the diff. | ||
| 2. **Adversarial layer** — the [[reducer-adversary-charter.md]] attack surface applied | ||
| to the changed code: can this change make the analyzer tell a plausible but false | ||
| story? Prefer findings expressed as a concrete failing input. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Scope reducer-specific review layers.
The charter applies reducer ADRs, the reducer checklist, and the reducer adversary charter to every cmtraceopen review. The load order makes those documents conditional on reducer or evidence-lane changes. For UI, packaging, documentation, or skill changes, the charter provides no contract or adversarial source and still requires every checklist question to be answered. Make these layers conditional, or define repository-wide inputs for non-reducer changes.
🤖 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 @.Clairvoyance/staff/code-review-charter.md around lines 27 - 35, Update the
review-layer requirements in the charter so the Contract and Adversarial layers
apply conditionally to reducer or evidence-lane changes, while UI, packaging,
documentation, and skill changes use repository-wide review inputs instead.
Ensure non-reducer reviews are not required to answer reducer-specific checklist
questions without applicable contract or adversarial sources.
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces a canonical CMTrace Open code-review charter under .Clairvoyance/staff/, adds two thin Claude skills (cmtraceopen-code-review, cmtraceopen-agent) that route reviewers/operators to the canonical docs, and wires the charter into .Clairvoyance/library.md so the routing index directs reviews to the new process.
Changes:
- Added
.Clairvoyance/staff/code-review-charter.mddefining load order, review layers, and report format for reviews. - Added two thin wrapper skills under
.claude/skills/to load agent context and run reviews via the charter. - Updated
.Clairvoyance/library.mdto route “code review” queries to the new charter.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
.claude/skills/cmtraceopen-code-review/SKILL.md |
Adds a “review” skill that routes to the canonical charter and describes expected review deliverable. |
.claude/skills/cmtraceopen-agent/SKILL.md |
Adds an “agent loader” skill that routes to repo-root agent context docs (soul.md, memory.md). |
.Clairvoyance/staff/code-review-charter.md |
Adds the canonical code-review contract (load order, recipe, report shape, constraints). |
.Clairvoyance/library.md |
Adds a new routing entry pointing code review requests to the charter. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+18
to
+22
| 3. For any change touching a reducer or evidence lane | ||
| (`crates/cmtraceopen-parser/src/intune/`, `src/sccm/`): the four ADRs in | ||
| `docs/architecture/decisions/`, the reducer review checklist in | ||
| `docs/superpowers/plans/2026-08-07-reducer-framework-v1.md`, and the | ||
| [[reducer-contract-charter.md]] hard rules. |
Comment on lines
+46
to
+49
| The deliverable is a report containing: findings ranked most-severe first; the named | ||
| gates and their observed states — CI checks, CodeRabbit review state | ||
| (`approved_at_head`, per the coderabbit-review-loop skill), and contract-layer | ||
| conformance; explicitly rejected review feedback with reasoning; and a closing line |
Comment on lines
+20
to
+24
| The deliverable is the charter's gate-state report: findings ranked most-severe | ||
| first, named gate states (CI, CodeRabbit `approved_at_head` via the | ||
| `coderabbit-review-loop` skill's state script, contract conformance), and rejected | ||
| feedback with reasoning. Merging is the repository owner's action; the review ends | ||
| at the report. |
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.
Adds the canonical code-review charter to the Clairvoyance staff org, routes it from library.md, and makes the structure invokable by the Claude Code operator via two thin skills (cmtraceopen-code-review, cmtraceopen-agent). Companion Hermes-side thin wrappers point at the same canonical files.
Built TDD: a cold-agent RED baseline (convention-blind review, self-authorized merge verdict) and a GREEN dry-run that followed the charter chain, applied contract-then-adversarial-then-mechanical layers, reported gate states without a merge verdict, and routed an ADR-004 ambiguity instead of deciding it locally.
🤖 Generated with Claude Code
Summary by CodeRabbit
cmtraceopenchanges.