hihol-labs/product-factory-os/review

Review

Review project documents and code. Lead with findings.

The canonical rubric lives in docs/rubrics/review.md. Use it as the source of truth.

For Product Factory OS projects, also apply docs/rubrics/pfo.md, docs/rubrics/strategy.md when strategy artifacts are in scope, and docs/rubrics/testing.md when implementation or deploy readiness is in scope.

Status

Return one:

• BLOCKED: at least one critical issue prevents the next step.
• PASSED_WITH_WARNINGS: critical checks pass, important issues remain.
• PASSED: critical and important checks pass.

Critical Checks

• Apply every Critical check from docs/rubrics/review.md.
• Apply Important and Nice-to-have checks after Critical checks.
• Do not invent additional blocking criteria unless they are security-critical.

Procedure

1. Detect scope:

• Planning docs only
• Code only
• Full project
• Methodology repository

1. Read the canonical rubric.
2. Inspect the required files for the selected scope.
3. For PFO projects, validate:

• product classification confidence and ambiguity
• template compliance
• Product Compiler artifacts
• execution graph semantics
• state consistency
• gate traceability
• Engineering Discipline v2 via scripts/validate_plan_quality.py <project>

1. For browser-facing changes, require /browser-check target, engine, flow, and screenshot/log evidence before deploy readiness.
2. For SDK, framework, or platform questions, use /mcp-docs before flagging documentation-sensitive findings.
3. Apply checks as binary pass/fail at Critical tier.
4. Run spec compliance review before code quality review for implementation units.
5. Produce findings first.
6. Set gate status from rubric results.

Scope Rules

• If no source code exists, skip code-only concerns and say docs-only review.
• If planning docs are missing, review available code but mark missing docs as Critical only when the workflow expects planning docs.
• If reviewing the methodology repository itself, run scripts/meta_review.py when available and include its result.
• If EXECUTION_GRAPH.md exists, run scripts/validate_execution_graph.py when available.
• If .codex-memory/STATE.json exists, check it matches current stage, current node, gate results, and next action.
• If TDD evidence is required, check red and green evidence before accepting the testing gate.
• If the work is a bugfix, check ROOT_CAUSE.md or equivalent state evidence before accepting the fix.

Output Format

1. Findings ordered by severity with file references.
2. Status enum.
3. Open questions.
4. Short summary.

Use this shape:

## Findings
 
-[Critical] C1 path:line - finding and impact.
 
## Gate
 
Status: BLOCKED | PASSED_WITH_WARNINGS | PASSED
 
| Tier | Pass | Total | Status |
|---|---:|---:|---|
| Critical | X | 10 | pass/fail |
| Important | Y | 8 | pass/warn |
| Nice | Z | 4 | info |
 
## Open Questions
 
## Summary

Self-validation

Before final output, verify:

• Route, side-effect, and confirmation requirements match metadata.
• Required artifacts or read-only result are explicit.
• Verification, blockers, and next route are stated.

Rules

• Be concrete: cite files and lines when possible.
• Do not soften BLOCKED by request.
• If no issues are found, say so and name residual risks.
• If the rubric and this skill conflict, follow the rubric and update this skill later.
• Separate findings from suggestions.
• Do not edit files during review unless the user explicitly asks for remediation after the report.

Common Failure Modes

• Missing acceptance criteria: block planning-to-code transition.
• Architecture names an entity that PRD never mentions: warn unless it creates implementation ambiguity.
• Tests missing for a changed user flow: block if release/deploy is requested, warn during early scaffolding.
• No deployment docs: block only when deploy is in scope.