docs(unic-pr-review): add PRD and ADRs 0001–0009#153
Merged
Conversation
Captures the full problem statement, 44 user stories, module list, schemas, testing decisions, and out-of-scope items for the standalone unic-pr-review plugin. Reflects the clean-slate doctrine (no code, prompts, fixtures, or soft dependency shared with the prior pr-review plugin) and the decisions crystallised during the EXPLORE phase of the abandoned PIV loop run: - Re-review Coordinator is an LLM agent, not a rule table (motto: get out of the models' way). - Aspect agents emit structured fields; pure-function renderers append the Bot Signature footer from scripts/lib/signature.mjs. - Approval Loop persists resumable state under <cwd>/.unic-pr-review/<key>/ with a self-ignoring .gitignore. - Providers ship as folder bundles (providers/<name>/) so future GitHub / GitLab support is a contained PR; work-item discovery is a Provider contract. Vertical-slice implementation is tracked in issues #143–#152 (label feature/unic-pr-review).
Records the load-bearing decisions for the unic-pr-review plugin: - 0001: multi-source intent gathering with shared Atlassian credentials. - 0002: confidence-scored Findings with explicit Severity thresholds. - 0003: interactive Approval Loop as the default write path. - 0004: hard-stop when promised intent sources are unreachable. - 0005: az CLI for Azure DevOps, custom HTTP for Atlassian. - 0006: iteration state lives in the PR, not locally. - 0007: Re-review uses a delta diff, not a full PR diff. - 0008: conditional sub-agent spawning over per-file chunking. - 0009: Pre-PR mode is a peer operating mode, not a flag. Two further ADRs are referenced in the PRD and will land with the slice that exercises them: an amendment to ADR-0001 capturing provider-owned work-item discovery, and a new ADR-0010 capturing the provider-folder- bundle decision.
orioltf
added
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the initial specification set for the upcoming unic-pr-review Claude Code plugin: a full PRD plus plugin-scoped ADRs describing key architectural decisions. This lands the documentation baseline for downstream implementation slices without introducing any runnable code.
Changes:
- Added
docs/issues/unic-pr-review/PRD.mddescribing the plugin scope, user stories, module boundaries, schemas, and testing decisions. - Added plugin-scoped ADR set
apps/claude-code/unic-pr-review/docs/adr/0001–0009plus an ADR indexREADME.md. - Documented core doctrines (clean-slate separation from
pr-review, confidence scoring, approval loop, delta re-review, provider abstraction).
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/issues/unic-pr-review/PRD.md | PRD defining requirements, module responsibilities, schemas, and testing strategy for unic-pr-review. |
| apps/claude-code/unic-pr-review/docs/adr/README.md | Index page for plugin-scoped ADRs. |
| apps/claude-code/unic-pr-review/docs/adr/0001-multi-source-intent-with-shared-atlassian-credentials.md | ADR on multi-source intent + shared Atlassian credentials. |
| apps/claude-code/unic-pr-review/docs/adr/0002-confidence-scored-findings.md | ADR on confidence scoring + severity thresholds. |
| apps/claude-code/unic-pr-review/docs/adr/0003-interactive-approval-as-default.md | ADR on interactive approval loop as the default write path. |
| apps/claude-code/unic-pr-review/docs/adr/0004-hard-stop-on-missing-doc-credentials.md | ADR on hard-stop semantics for unreachable intent sources. |
| apps/claude-code/unic-pr-review/docs/adr/0005-az-cli-over-rest.md | ADR on az devops invoke for ADO and REST for Atlassian. |
| apps/claude-code/unic-pr-review/docs/adr/0006-iteration-state-in-pr.md | ADR on iteration state living in PR threads/signatures (no local cache). |
| apps/claude-code/unic-pr-review/docs/adr/0007-delta-diff-for-re-review.md | ADR on delta diffs for re-review. |
| apps/claude-code/unic-pr-review/docs/adr/0008-conditional-sub-agent-spawning.md | ADR on conditional aspect-agent spawning (no per-file chunking). |
| apps/claude-code/unic-pr-review/docs/adr/0009-pre-pr-mode-as-peer-of-pr-modes.md | ADR on Pre-PR mode as a peer operating mode (argument-shape driven). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ink + node:fetch wording Addresses Copilot review on PR #153. - Reformat all 9 ADRs (0001–0009) to the repo's MADR-lite shape: `# NNNN. Title`, `**Status:** Accepted (2026-05)`, `## Context`, `## Decision`, `## Consequences`. Existing "Considered options" framing folds into Context; the chosen path is rephrased in Decision. Matches docs/adr/0001-pnpm-workspaces-no-turborepo.md. (Copilot comments 2, 3, 4, 5, 7, 8, 9, 10, 11) - Fix the monorepo-ADR relative link in apps/claude-code/unic-pr-review/ docs/adr/README.md: `../../../docs/adr/` → `../../../../../docs/adr/`. (Copilot comment 1) - Replace the `node:fetch` misnomer in ADR-0005 with Node's global `fetch` (built into Node 22+). Architectural decision (CLI for ADO, REST for Atlassian) unchanged. (Copilot comment 6)
…ops login, provider bundle naming, and ADR-0010 status Addresses Copilot review on PR #153. - §13 (Solution): "seven Review Aspect sub-agents" → "six Review Aspect sub-agents in parallel (the Intent Checker runs first as a separate non-aspect agent)". The Intent Checker is not an aspect agent. (Copilot comment 12) - §80 (Atlassian Fetcher): drop the `node:fetch` misnomer; use Node's built-in global `fetch` (Node 22+). (Copilot comment 13) - §94 (ADR list link): label and target now both point at `apps/claude-code/unic-pr-review/docs/adr/`, eliminating the ambiguity with the monorepo-wide `docs/adr/`. (Copilot comment 14) - §105 / §107: mark ADR-0010 explicitly as "(planned) — lands with the slice that exercises the provider abstraction (issue #148)". Same treatment for the planned ADR-0001 amendment on provider-owned work-item discovery. The PR ships ADRs 0001–0009 only. (Copilot comment 15) - §202 (Out of Scope): "only azure_devops.js ships" → "ships as a folder bundle layout (providers/<name>/) but only providers/azure_devops/ is implemented in v2". Aligns with §40 and §79. (Copilot comment 16) - US 34 (~§55) and the Doctor bullet in Specific Interactions (~§191): both now say `az devops login` consistently. Grep confirms no stray `az login` references remain in the PRD. (Copilot comments 17, 18)
Tightens the PRD and ADRs after the multi-agent review pass: Critical fixes - PRD §94: ADR list link target was `../../apps/...` (two ..s, resolves to a non-existent dir). Fixed to `../../../apps/...` (three ..s). - ADR-0008 §12 rejected-alternative text: "running all seven agents on every Review" → "running all six aspect agents on every Review (plus the Intent Checker, which always runs first)". Aligns with the PRD and US 44 which both say six aspect agents. - US 34 (PRD §55): adds an explicit Doctor check that `az devops user show --user me` resolves, so identity caching will succeed at review time. Closes the gap with ADR-0006 §21 which says Doctor verifies this lookup. Important fixes - ADR README: adds a "Planned" section listing ADR-0010 (provider folder bundle) and the planned amendment to ADR-0001 (provider-owned work-item discovery), both scheduled to land with issue #148. - PRD §172 (Specific interactions): adds a one-line preamble noting that every bullet describes planned behaviour scheduled to land in issues #143–#152. Prevents future readers from mistaking the PRD for a description of shipped code. - ADR-0006: clarifies that the rejected `~/.unic-pr-review/state.json` is NOT the same thing as the accepted `<cwd>/.unic-pr-review/<key>/` cache used by the Approval Loop. Cross-references PRD §81. - PRD §213: "Until then both coexist" → "As of 2026-05 both coexist" so the dating doesn't rot once `pr-review` is deleted. - PRD §215: "before the first commit lands" rotted on this PR (which IS the first commit). Reworded to point at issue #143 (plugin scaffold) which also creates the CONTEXT.md the map refers to. High-value polish - PRD Review Summary and Inline Comment schemas: replace the literal `🤖 Reviewed by Claude Code — Iteration N` with `{BOT_SIGNATURE_FOOTER}`, with a note pointing at scripts/lib/signature.mjs (ADR-0006) as the canonical source. The literal previously appeared in 5+ places across the PRD; the placeholder removes a docs-rot tripwire. - Review Summary schema: adds a concrete `AC 1: addressed` example under the Intent Check block so the format US 6 promises is locked in writing.
This was referenced May 28, 2026
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.
Summary
Lands the documentation foundation for the upcoming
unic-pr-reviewplugin (v2.0.0) — its PRD and the nine architectural decision records that govern it. No code, no scaffold, no plugin manifest in this PR; just the spec.docs/issues/unic-pr-review/PRD.md— full PRD: problem statement, 44 user stories, module list, schemas (Review Summary, Inline Comment, Credentials), testing decisions, out-of-scope, and the clean-slate doctrine (no code/prompts/fixtures shared with the priorpr-reviewplugin).apps/claude-code/unic-pr-review/docs/adr/0001–0009 + README.md— the load-bearing ADRs covering multi-source intent, confidence-scored findings, the interactive Approval Loop, hard-stop semantics, theazCLI / Atlassian HTTP split, in-PR iteration state, delta-diff re-review, conditional sub-agent spawning, and Pre-PR as a peer mode.Why
These artefacts crystallised during a long EXPLORE-phase grilling session (now rejected as a PIV-loop run — vertical-slice implementation via Archon-runner is the chosen path forward). Landing them on
developgives every downstream implementation slice (issues #143–#152) a stable spec to write against. Two follow-up ADR updates are referenced in the PRD and will land with the slice that exercises them:Test plan
docs/adr/).pnpm ci:checkis the only relevant CI gate.pnpm ci:checkis green.Related
feature/unic-pr-review) — the 10 tracer-bullet vertical slices that implement what this PRD describes..claude/prompts/unic-pr-review-archon-rollout.prompt.md(untracked by design).