feat: redesign document-review skill with persona-based review#359
feat: redesign document-review skill with persona-based review#359
document-review skill with persona-based review#359Conversation
Define requirements for replacing document-review with a persona-based review pipeline. 2 always-on personas (coherence, feasibility) + 4 conditional (product-lens, design-lens, security-lens, scope-guardian) with hybrid action model (auto-fix quality issues, present strategic questions for user decision).
Implementation plan with 4 units: create always-on agents (coherence, feasibility), conditional agents (product-lens, design-lens, security-lens, scope-guardian), rewrite document-review SKILL.md with persona pipeline orchestration, and update README. Includes structured findings schema, fingerprint-based dedup, residual concern promotion, and per-persona confidence calibration.
…security-lens, scope-guardian)
… to review agents Product-lens gains failure-mode inversion (Munger) and trajectory check; feasibility gains systematic 4-path tracing for data flows.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 73b8b9d610
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Drop the 4-class enum (safe_auto/gated_auto/manual/advisory) carried for hypothetical ce:review-beta compatibility. Document review only needs two buckets: apply automatically or present to user. Also removes owner and requires_verification fields from the schema.
Address PR review feedback: Phase 3.1 was listing a subset of required fields instead of referencing the schema definition, which could miss validating autofix_class.
tmchow
changed the title
document-review skill with persona-based review
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a8afb8ac5e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Address PR review feedback: - Dedup now skips merging when findings recommend opposing actions, preserving both for contradiction resolution - Auto findings without suggested_fix get demoted to present
Set coherence-reviewer to model: haiku -- its work (terminology drift, contradiction detection, cross-reference checking) is pattern matching that doesn't benefit from larger models. Fix converters to omit model field when inherit instead of emitting literal string (droid, copilot). Update OpenCode sonnet alias to claude-sonnet-4-6.
tmchow
force-pushed
the
feat/plan-review-personas
branch
from
7acdc24 to
4df757b
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4df757b46b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (agent.model && agent.model !== "inherit") { | ||
| frontmatter.model = agent.model | ||
| } |
There was a problem hiding this comment.
model: inherit when converting droids
Factory droids treat model: inherit as a distinct runtime choice (use the parent session model), but this change drops the model field whenever a Claude agent is marked inherit. That means converted droids no longer explicitly inherit and can fall back to Factory defaults, causing behavior/cost drift for plugins that rely on parent-model alignment. Keep emitting model: "inherit" for this target instead of omitting it.
Useful? React with 👍 / 👎.
1 participant
Summary
The existing
document-reviewskill uses a single-voice reviewer that tries to evaluate planning documents across all dimensions simultaneously. This produces shallow, unfocused feedback -- the reviewer context-switches between product strategy, technical feasibility, design completeness, security, scope, and consistency without going deep on any of them.This PR replaces that with a multi-persona pipeline that dispatches specialized reviewer agents in parallel, each focused on a single analytical lens:
Always-on personas (run on every document)
Conditional personas (activated by content signals in the document)
Pipeline architecture
The orchestrator skill (SKILL.md) handles the full lifecycle:
Reference files
findings-schema.json-- JSON schema for structured findings with 2-class autofix routing (auto/present)subagent-template.md-- shared prompt template with variable slots for consistent agent dispatchreview-output-template.md-- markdown output format for the synthesized reviewKey design decisions
<examples>blocks -- these agents are always dispatched by the orchestrator, never auto-triggered, so triggering examples waste tokensauto/present) -- findings are either deterministic fixes the orchestrator applies without asking, or they require user judgment. No middle ground needed for document review.Test plan
bun run release:validateto verify plugin/marketplace consistencydocument-reviewskill on a requirements document and verify conditional persona selectiondocument-reviewskill on a technical plan and verify all 6 personas activate