QIP Proposal Review
Review a QIP without substituting for its human approvers. Use qv-qip-create for first drafts and qv-qip-triage to decide whether a QIP is needed.
Ground the review
- Read ../qv-qip-create/references/qip-template.md.
- Read
docs/architecture/PRINCIPLES.md.
- When the proposal changes runtime, package, plugin, registry, storage, transport, security, public API, release, or deployment boundaries, check its system fit against
docs/architecture/ARCHITECTURE.md and the relevant current repository sources.
Do not infer approval, commitments, current behavior, or implementation feasibility without evidence. Treat principle conflicts as review findings, not automatic rejection, unless the proposal hides or misrepresents the conflict.
Review criteria
Decision readiness
- Problem explains what matters and why a decision is needed now.
- Solution recommends one direction and states the exact approval ask.
- Architectural responsibilities, boundaries, interactions, and rationale are concrete enough to evaluate.
- Obvious alternatives are addressed briefly, with supporting research summarized in the Appendix when needed.
- Consequences state positive impact and the trade-offs reviewers must accept.
- Decision-relevant trust-boundary, compatibility, migration, and release effects are explicit.
- Likely scope misunderstandings are excluded explicitly, and the approvers table is preserved.
An unclear or absent recommended direction or approval ask is a blocker. Do not use length as a proxy for this check.
Decision-brief quality
- Use 600-900 words as the target and 1,200 words as a soft ceiling for the core proposal, excluding the approvers table and Appendix.
- Length above the ceiling is a suggested edit, not a blocker by itself.
- Flag specific passages when repetition or implementation detail buries the problem, recommended direction, architectural boundary, or accepted trade-offs.
- Recommend removing file lists and moving useful APIs, protocols, execution steps, test plans, rollout detail, failure-mode analysis, and large comparisons to the Appendix unless they directly affect approval.
- Check that the Appendix is relevant and organized, research has been synthesized rather than reproduced, external artifacts explain their relevance, principle references explain a concrete fit or conflict, and images are linked rather than embedded as base64 data.
Consultation
If consultation context is provided, check coverage of the owning team lead, Lead / Architect, and any relevant cross-cutting expertise. The consultation note belongs outside the Canvas-ready QIP, so its absence from the QIP is not a finding. Advice is direction plus reasoning, not a vote.
Findings and severity
Separate:
- Blockers: the decision cannot responsibly be approved, such as no clear approval ask, an unsupported material claim, an unresolved architectural contradiction, or missing impact that could change the decision.
- Clarifying questions: answers would improve confidence but may not require restructuring the proposal.
- Suggested edits: concision, organization, Appendix moves, and other improvements that do not block the decision.
Lead with findings ordered by approval risk and use line-specific references when possible:
## Blockers
- ...
## Clarifying questions
- ...
## Suggested edits
- ...
## Approval readiness
Ready | Ready with minor edits | Not ready
## Slack comment
<optional concise paste-ready comment if requested>
Say explicitly when there are no blockers. Do not rewrite the whole QIP unless asked. Keep an optional Slack comment under one screen.
1---2name: qv-qip-review3description: Reviews QIP drafts for approval readiness, architectural fit, decision clarity, material trade-offs, and appropriate stakeholder detail. Use when reviewing a QIP or invoking /qv-qip-review.4---56# QIP Proposal Review78Review a QIP without substituting for its human approvers. Use `qv-qip-create` for first drafts and `qv-qip-triage` to decide whether a QIP is needed.910## Ground the review11121. Read [../qv-qip-create/references/qip-template.md](../qv-qip-create/references/qip-template.md).132. Read `docs/architecture/PRINCIPLES.md`.143. When the proposal changes runtime, package, plugin, registry, storage, transport, security, public API, release, or deployment boundaries, check its system fit against `docs/architecture/ARCHITECTURE.md` and the relevant current repository sources.1516Do not infer approval, commitments, current behavior, or implementation feasibility without evidence. Treat principle conflicts as review findings, not automatic rejection, unless the proposal hides or misrepresents the conflict.1718## Review criteria1920### Decision readiness2122- Problem explains what matters and why a decision is needed now.23- Solution recommends one direction and states the exact approval ask.24- Architectural responsibilities, boundaries, interactions, and rationale are concrete enough to evaluate.25- Obvious alternatives are addressed briefly, with supporting research summarized in the Appendix when needed.26- Consequences state positive impact and the trade-offs reviewers must accept.27- Decision-relevant trust-boundary, compatibility, migration, and release effects are explicit.28- Likely scope misunderstandings are excluded explicitly, and the approvers table is preserved.2930An unclear or absent recommended direction or approval ask is a blocker. Do not use length as a proxy for this check.3132### Decision-brief quality3334- Use 600-900 words as the target and 1,200 words as a soft ceiling for the core proposal, excluding the approvers table and Appendix.35- Length above the ceiling is a suggested edit, not a blocker by itself.36- Flag specific passages when repetition or implementation detail buries the problem, recommended direction, architectural boundary, or accepted trade-offs.37- Recommend removing file lists and moving useful APIs, protocols, execution steps, test plans, rollout detail, failure-mode analysis, and large comparisons to the Appendix unless they directly affect approval.38- Check that the Appendix is relevant and organized, research has been synthesized rather than reproduced, external artifacts explain their relevance, principle references explain a concrete fit or conflict, and images are linked rather than embedded as base64 data.3940### Consultation4142If consultation context is provided, check coverage of the owning team lead, Lead / Architect, and any relevant cross-cutting expertise. The consultation note belongs outside the Canvas-ready QIP, so its absence from the QIP is not a finding. Advice is direction plus reasoning, not a vote.4344## Findings and severity4546Separate:4748- **Blockers:** the decision cannot responsibly be approved, such as no clear approval ask, an unsupported material claim, an unresolved architectural contradiction, or missing impact that could change the decision.49- **Clarifying questions:** answers would improve confidence but may not require restructuring the proposal.50- **Suggested edits:** concision, organization, Appendix moves, and other improvements that do not block the decision.5152Lead with findings ordered by approval risk and use line-specific references when possible:5354```markdown55## Blockers56- ...5758## Clarifying questions59- ...6061## Suggested edits62- ...6364## Approval readiness65Ready | Ready with minor edits | Not ready6667## Slack comment68<optional concise paste-ready comment if requested>69```7071Say explicitly when there are no blockers. Do not rewrite the whole QIP unless asked. Keep an optional Slack comment under one screen.
tetherto