docs(unic-pr-review): ratify spawn-gating parity contract (ADR-0008 amendment + PRD elevation)#219
Conversation
…mendment + PRD elevation) Amend ADR-0008 to permit Y-det hybrid content-gated spawning for the comment, errors, and types semantic gates (while keeping path classification as the fast path). Records the bias-toward-spawn rationale and flags the errors gate as the first Y-llm-promotion candidate. Realigns PRD §Testing to explicitly name the three content-aware gates and elevates the toolkit relationship from "loosely inspired" to a documented behavioural-parity contract for code-analysis aspects, preserving the clean-slate doctrine. Resolves the three-way contradiction between PRD :203, ADR-0008, and the path-only implementation. Closes #212. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
🔍 Comprehensive PR ReviewPR: #219 — docs(unic-pr-review): ratify spawn-gating parity contract SummaryA clean docs-only PR that fully resolves the three-way contradiction between PRD Verdict: ✅
🟢 Low Issues (Optional)L1 — Spawn Table header stale + three semantic gate rows have no amendment pointer📍 The Spawn Table header reads Options: Fix Now | Create Issue | Skip View suggested fix (4-line change)### Spawn Table (as of PR #158; rows marked † amended by 2026-06 content-gating — see amendment section below)
| Agent | Spawn condition |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| `code-reviewer` | Always — any non-empty diff |
| `silent-failure-hunter` | † At least one non-test source file (`.mjs`, `.cjs`, `.js`, `.ts`, `.tsx`, `.jsx`; excluding `.d.ts`) |
| `type-design-analyzer` | † At least one `.d.ts`, `.ts`, `.tsx`, or file under `types/`, `schemas/`, `interfaces/` |
| `pr-test-analyzer` | At least one test file (`.test.*`, `.spec.*`, or under `tests/`, `__tests__/`) |
| `comment-analyzer` | † At least one `.md` / `.mdx` file or file under `docs/` |
| `code-simplifier` | Three or more non-test source files (excluding `.d.ts`) |
† Path classification is the fast path; additionally gated by deterministic diff-content sampling per the amendment below.Recommendation: Fix Now — both agents agree it's a 4-line change with disproportionate discoverability value for implementation issues #213–#215. L2 — CONTEXT.md "Spawn Set" definition is narrower than the amended decision📍 The definition reads Options: Fix Now | Skip View suggested fix (1-line change)**Spawn Set**:
The `Set<string>` of Review Aspect agent names returned by `decideSpawnSet()` in `scripts/lib/changed-file-analyser.mjs`. Computed once before any agent runs, based on changed-file categories (ADR-0008); additionally content-aware for the three semantic gates (`comment-analyzer`, `silent-failure-hunter`, `type-design-analyzer`) via deterministic diff-content sampling (ADR-0008 amendment, 2026-06).
_Avoid_: agent list, run set, active agentsL3 — "match" in PRD
|
| Issue Title | Priority | Related Finding |
|---|---|---|
| "Annotate ADR-0008 Spawn Table for Y-det amended gates" | P3 | L1 (if deferred) |
| "Update CONTEXT.md Spawn Set definition for content-aware gates" | P3 | L2 (if deferred) |
| "Y-det gate implementation guide (regex fixtures + diff-hunk parsing)" | P2 | L4 — deferred to #213–#215 |
Reviewed by Archon comprehensive-pr-review workflow
Full artifact: /Users/oriol.torrent/.archon/workspaces/unic/unic-agents-plugins/artifacts/runs/90d7ce3479271d9dae8e3e66712383a0/review/consolidated-review.md
…e, update CONTEXT.md, clarify PRD parity claim - L1: annotate ADR-0008 Spawn Table header (as of PR #158; rows marked † amended by 2026-06) and add † markers + footnote to the three Y-det semantic gate rows so implementors reading the table alone see the content-gating layer - L2: extend CONTEXT.md Spawn Set definition to mention content-aware sampling for comment-analyzer, silent-failure-hunter, type-design-analyzer (ADR-0008 amendment, 2026-06) - L3: replace "match" with "approximate" in PRD :229 to remove mechanism-equivalence ambiguity (Y-det derives outcomes equivalent to toolkit's Y-llm, not identical in mechanism) Deferred: L4 (Y-det gate implementation guide) — out of scope, tracked by #213–#215. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
⚡ Self-Fix Report (Aggressive)Status: COMPLETE Fixes Applied (3 total)
View all fixes
Tests Added(none — docs-only PR) Skipped (0)(none — all findings addressed) Deferred (1 — out of scope)
Validation✅ Type check | ✅ Biome + Prettier (223 files) | ✅ Tests (38 passed) Self-fix by Archon · aggressive mode · fixes pushed to |
There was a problem hiding this comment.
Pull request overview
This PR updates the unic-pr-review documentation set to formalize a “spawn-gating parity contract” and to amend ADR-0008 so the changed-file analyser may use deterministic diff-content sampling (Y-det) for the three semantic gates (comments/errors/types), resolving prior PRD↔ADR↔implementation contradictions.
Changes:
- PRD: clarifies the changed-file analyser as content-aware for comment/errors/types and elevates toolkit alignment to a documented behavioural-parity contract.
- ADR-0008: amends the spawning doctrine to allow Y-det hybrid content-gated spawning for the three semantic gates, with a bias toward spawning on ambiguity.
- CONTEXT: updates the Spawn Set definition to reflect the semantic-gate content awareness.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| apps/claude-code/unic-pr-review/docs/issues/unic-pr-review/PRD.md | Updates testing/spec wording to explicitly include deterministic content-aware gating and elevates toolkit parity to a contract. |
| apps/claude-code/unic-pr-review/docs/adr/0008-conditional-sub-agent-spawning.md | Amends ADR-0008 to permit deterministic diff-content sampling for the three semantic spawn gates and documents rationale. |
| apps/claude-code/unic-pr-review/CONTEXT.md | Updates glossary/contract text for “Spawn Set” to include the ADR-0008 amendment. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Decision | ||
|
|
||
| The Plugin reviews a PR by fanning out to specialised Review Aspect sub-agents in parallel, each handling the whole diff under one lens. Spawning is conditional on what the diff contains — `code-reviewer` always runs; `pr-test-analyzer` runs only when test files changed; `silent-failure-hunter` runs when at least one non-test source file changed (a path/extension heuristic, not diff-content inspection); etc. The Plugin does NOT split the diff into per-file chunks. | ||
| The Plugin reviews a PR by fanning out to specialised Review Aspect sub-agents in parallel, each handling the whole diff under one lens. Spawning is conditional on what the diff contains — `code-reviewer` always runs; `pr-test-analyzer` runs only when test files changed; `silent-failure-hunter` runs when at least one non-test source file changed (a path/extension heuristic, not diff-content inspection — see amendment 2026-06 for the three semantic gates); etc. The Plugin does NOT split the diff into per-file chunks. |
| | `comment-analyzer` | † At least one `.md` / `.mdx` file or file under `docs/` | | ||
| | `code-simplifier` | Three or more non-test source files (excluding `.d.ts`) | | ||
|
|
||
| † Path classification is the fast path; additionally gated by deterministic diff-content sampling per the amendment below. |
| | `silent-failure-hunter` | † At least one non-test source file (`.mjs`, `.cjs`, `.js`, `.ts`, `.tsx`, `.jsx`; excluding `.d.ts`) | | ||
| | `type-design-analyzer` | † At least one `.d.ts`, `.ts`, `.tsx`, or file under `types/`, `schemas/`, `interfaces/` | | ||
| | `pr-test-analyzer` | At least one test file (`.test.*`, `.spec.*`, or under `tests/`, `__tests__/`) | | ||
| | `comment-analyzer` | † At least one `.md` / `.mdx` file or file under `docs/` | | ||
| | `code-simplifier` | Three or more non-test source files (excluding `.d.ts`) | |
|
|
||
| - The Plugin retires the existing `apps/claude-code/pr-review` Plugin after acceptance testing. As of 2026-05 both coexist in the monorepo as **fully independent** Plugins — `unic-pr-review` shares no code, no prompts, no fixtures, and no soft dependency with `pr-review`. The maintainer will delete `pr-review` once `unic-pr-review` proves itself on the two target projects (one ADO, one Jira). | ||
| - The six aspect agents are written from scratch in this Plugin's own voice with our Confidence-Score rubric embedded verbatim. The conditional-spawning pattern is loosely inspired by Anthropic's `pr-review-toolkit`, but we take no soft dependency and copy no prompts. | ||
| - The six code-analysis aspect agents maintain a **behavioural-parity contract** with Anthropic's `pr-review-toolkit`: their spawn-gating conditions and analysis behaviour approximate the toolkit's semantic patterns for the comment, error-handling, and types aspects. The clean-slate doctrine holds — no code, no prompts, and no fixtures are taken from `apps/claude-code/pr-review/`; parity is by independent derivation against this PRD and the ADRs (see ADR-0008 amendment, issue #212). |
Summary
Why
Resolves the three-way contradiction between PRD
:203("content sample"), ADR-0008 ("not diff-content inspection"), and the path-only implementation. This is the contract document that all subsequent spawn-gating implementation slices (#213–#215) cite; it lands before implementation.Wording requires maintainer sign-off on this PR (HITL — decisions are locked, exact text needs approval).
Closes #212.
Test plan
:203: Changed-file analyser described as content-aware with the three semantic gates named:229: "loosely inspired" replaced with behavioural-parity contract language🤖 Generated with Claude Code