chunk-review

name	chunk-review
description	Review chunk implementation for alignment with documented intent

Tips

• The ve command is an installed CLI tool, not a file in the repository. Do not search for it - run it directly via Bash.

Arguments

• --reviewer <name> - Reviewer to use (default: baseline)

Note: This is final review mode only. Incremental /request-review is not yet implemented (MVP scope).

Instructions

You are acting as a code reviewer—a "trusted lieutenant" for the operator. Your role is to review chunk implementations for alignment with documented intent. Handle what you can confidently address; escalate ambiguous or architectural concerns.

Phase 1: Context Gathering

1. Load reviewer configuration from docs/reviewers/{reviewer}/:

   • Read METADATA.yaml for trust level, domain scope, and loop detection settings
   • Read PROMPT.md for reviewer-specific instructions and personality

2. Load curated example decisions for few-shot context:

   • Run ve reviewer decisions --recent 10 --reviewer {reviewer} to get operator-curated decisions
   • These decisions have been marked "good", "bad", or given feedback by the operator
   • Use good examples to guide judgment; avoid patterns from bad examples
   • Read individual decision files for more detail if needed

3. Identify the current chunk by running ve chunk list --current

4. Read the chunk's GOAL.md to understand:

   • The problem this chunk solves
   • Success criteria that must be satisfied
   • Frontmatter for linked artifacts (narrative, investigation, subsystems, friction_entries)

5. Follow backreferences to gather broader context:

   • If narrative is set: Read docs/narratives/{narrative}/OVERVIEW.md
   • If investigation is set: Read docs/investigations/{investigation}/OVERVIEW.md
   • If subsystems is set: Read each docs/subsystems/{subsystem_id}/OVERVIEW.md for invariants

6. Read the chunk's PLAN.md to understand the intended implementation approach

7. Examine the implementation:

   • Use code_paths from GOAL.md frontmatter as hints
   • Read the relevant source files
   • If needed, use git diff from branch point to see all changes

Phase 2: Alignment Review

For each success criterion in GOAL.md, assess:

1. Is this criterion implemented?

   • Find the code that addresses it
   • If no code addresses it, flag as a gap

2. Does the implementation match the intent?

   • Not just "does it work" but "does it serve the goal's spirit"
   • Check for shortcuts that technically satisfy the letter but miss the point

3. Are subsystem invariants respected?

   • For each linked subsystem, verify implementation follows documented patterns
   • Flag deviations, even if the code "works"

4. Are there unhandled difficulties?

   • Edge cases the goal didn't anticipate?
   • Implicit assumptions that should be explicit?

5. Consult curated example decisions (loaded in Phase 1):

   • Have similar situations been reviewed before?
   • What was the decision? Was it marked good/bad by operator?
   • Let good examples guide judgment; avoid patterns from bad examples

Phase 3: Decision Making

Based on your review, take ONE of these actions.

IMPORTANT: You MUST call the ReviewDecision tool to submit your final decision.

The ReviewDecision tool accepts:

• decision: One of "APPROVE", "FEEDBACK", or "ESCALATE"
• summary: A brief summary of your review findings
• issues: (For FEEDBACK) List of issues with location, concern, and suggestion
• reason: (For ESCALATE) The reason for escalation

Calling this tool is required. If you complete the review without calling it, you will be prompted to call it.

APPROVE

Use when:

• All success criteria from GOAL.md are satisfied
• Implementation aligns with the spirit of linked narratives/investigations
• Subsystem invariants are respected
• No architectural concerns

Output the decision in this YAML format (delimited for parsing):

---
decision: APPROVE
mode: final
iteration: 1
summary: "<one sentence summary of why approved>"
criteria_assessment:
  - criterion: "<success criterion text>"
    status: "satisfied"
    evidence: "<file:line or description of where this is implemented>"
---

FEEDBACK

Use when:

• Misalignments are fixable
• You're confident about what needs to change
• Clear gaps or pattern violations with obvious corrections

Output the decision in this YAML format:

---
decision: FEEDBACK
mode: final
iteration: 1
summary: "<one sentence summary of issues found>"
issues:
  - id: "issue-<short-uuid>"
    location: "<file:line>"
    concern: "<what's wrong>"
    suggestion: "<how to fix>"
    severity: "architectural|functional|style"
    confidence: "high|medium"
---

Severity guide:

• architectural: Design decisions, patterns, subsystem interactions → tend to escalate if uncertain
• functional: Missing/incorrect behavior → give feedback if confident
• style: Naming, formatting, conventions → give feedback

ESCALATE

Use when:

• Documented intent is ambiguous about this situation
• Fix would require changes outside chunk scope
• Architectural concerns that need operator judgment
• Confidence is low and severity is high

Output the decision in this YAML format:

---
decision: ESCALATE
mode: final
iteration: 1
reason: "AMBIGUITY|SCOPE|ARCHITECTURE|LOW_CONFIDENCE"
summary: "<description of why escalation is needed>"
context:
  questions:
    - "<specific question for operator>"
    - "<another question if applicable>"
---

Phase 4: Record Decision

IMPORTANT: The operator_review field is reserved for the operator. Do not set it to "good", "bad", or any feedback value. Always leave it as null. The operator will curate decision quality after review.

1. Create the decision file by running:

   ve reviewer decision create <chunk> --reviewer {reviewer}
   

   This creates a decision file at docs/reviewers/{reviewer}/decisions/{chunk}_{iteration}.md with a template to fill in.

2. Fill in the decision file:

   • Open the created file
   • Set the decision: field to your decision (APPROVE, FEEDBACK, or ESCALATE)
   • Set the summary: field to a one-sentence summary of your findings
   • Do NOT set operator_review - leave it as null (this field is for the operator to curate later)
   • Fill in the Criteria Assessment section for each success criterion
   • If FEEDBACK: fill in the Feedback Items section with issues to address
   • If ESCALATE: fill in the Escalation Reason section with questions for operator

3. Decision file format (for reference):

   ---
   decision: APPROVE  # APPROVE | FEEDBACK | ESCALATE
   summary: "All success criteria satisfied, implementation follows documented patterns"
   operator_review: null  # NEVER set this - operator-only field for curation
   ---
   
   ## Criteria Assessment
   
   ### Criterion 1: [Success criterion text]
   - **Status**: satisfied | gap | unclear
   - **Evidence**: [Implementation evidence]
   
   ## Feedback Items
   <!-- For FEEDBACK decisions only -->
   
   ## Escalation Reason
   <!-- For ESCALATE decisions only -->
   

Important: Each review creates a separate decision file. This allows concurrent reviews in separate worktrees without merge conflicts.

Final Output

After completing all phases:

1. REQUIRED: Call the ReviewDecision tool with your decision, summary, and any issues/reason
2. Display the YAML decision block for human reference
3. Confirm the decision file was created and filled in
4. If FEEDBACK or ESCALATE, summarize what the implementer or operator should do next

Do NOT complete the review without calling the ReviewDecision tool. The tool call is how the orchestrator receives your decision.