spec-kitty.review

Prompt file imported from wildcard/caro (.codex/prompts/spec-kitty.review.md). Fill in {{arguments}} before use. Copyright stays with the author.

Path: .kittify/templates/commands/review.md

User Input

{{arguments}}

You MUST consider the user input before proceeding (if not empty).

Location Pre-flight Check (CRITICAL for AI Agents)

BEFORE PROCEEDING: Verify you are working from inside the feature worktree.

Check current working directory and branch:

pwd
git branch --show-current

Expected output:

• pwd: /path/to/project/.worktrees/004-feature-name (or similar)
• Branch: 004-feature-name (NOT main or release/x.x.x)

If you see main or release/* branch, OR if pwd shows the main repo:

⛔ STOP - You are in the wrong location!

DO NOT use cd to navigate to the worktree. File editing tools (Edit, Write) will still use your original working directory.

Instead:

1. Tell the user: "This command must be run from inside the worktree at .worktrees/<feature>/"
2. Stop execution
3. Wait for the user to restart the session from the correct location

Path reference rule: Always use paths relative to the worktree root (e.g., kitty-specs/004-feature/tasks/). When communicating with the user, mention absolute paths for clarity.

This is intentional - worktrees provide isolation for parallel feature development.

Outline

1. Run .kittify/scripts/bash/check-prerequisites.sh --json --include-tasks from repo root; capture FEATURE_DIR, AVAILABLE_DOCS, and tasks.md path.

2. Determine the review target:

   • If user input specifies a filename, validate it exists under tasks/for_review/ (support phase subdirectories).
   • Otherwise, select the oldest file in tasks/for_review/ (lexical order is sufficient because filenames retain task ordering).
   • Abort with instructional message if no files are waiting for review.

3. Load context for the selected task:

   • Read the prompt file frontmatter (lane MUST be for_review); note task_id, phase, agent, shell_pid.
   • Read the body sections (Objective, Context, Implementation Guidance, etc.).
   • Consult supporting documents as referenced: constitution, plan, spec, data-model, contracts, research, quickstart, code changes.
   • Review the associated code in the repository (diffs, tests, docs) to validate the implementation.

4. Conduct the review:

   • Verify implementation against the prompt’s Definition of Done and Review Guidance.
   • Run required tests or commands; capture results.
   • Document findings explicitly: bugs, regressions, missing tests, risks, or validation notes.

5. Decide outcome:

• Needs changes:
  • CRITICAL: Insert detailed feedback in the ## Review Feedback section (located immediately after the frontmatter, before Objectives). This is the FIRST thing implementers will see when they re-read the prompt.
  • Use a clear structure:

    ## Review Feedback
    
    **Status**: ❌ **Needs Changes**
    
    **Key Issues**:
    1. [Issue 1] - Why it's a problem and what to do about it
    2. [Issue 2] - Why it's a problem and what to do about it
    
    **What Was Done Well**:
    - [Positive note 1]
    - [Positive note 2]
    
    **Action Items** (must complete before re-review):
    - [ ] Fix [specific thing 1]
    - [ ] Add [missing thing 2]
    - [ ] Verify [validation point 3]

  • Update frontmatter:
    • Set lane: "planned"
    • Set review_status: "has_feedback"
    • Set reviewed_by: <YOUR_AGENT_ID>
    • Clear assignee if needed
  • Append a new entry in the prompt's Activity Log with timestamp, reviewer agent, shell PID, and summary of feedback.
  • Run .kittify/scripts/bash/tasks-move-to-lane.sh <FEATURE> <TASK_ID> planned --note "Code review complete: [brief summary of issues]" (use the PowerShell equivalent on Windows) so the move and history update are staged consistently.
• Approved:
  • Use the dedicated approval command to ensure proper reviewer attribution:

    # Capture reviewer identity
    REVIEWER_AGENT=<YOUR_AGENT_ID>  # e.g., "claude-reviewer" or from $AGENT_ID
    REVIEWER_SHELL_PID=$$           # Current shell PID
    
    # Use tasks-approve command for proper review attribution
    python3 .kittify/scripts/tasks/tasks_cli.py approve <FEATURE> <TASK_ID> \
      --review-status "approved without changes" \
      --reviewer-agent "$REVIEWER_AGENT" \
      --reviewer-shell-pid "$REVIEWER_SHELL_PID"

  • This automatically:
    • Sets lane: "done"
    • Sets review_status: "approved without changes" (or your custom status)
    • Sets reviewed_by: <YOUR_AGENT_ID>
    • Updates agent: <YOUR_AGENT_ID> and shell_pid: <YOUR_SHELL_PID>
    • Appends Activity Log entry with reviewer's info (NOT implementer's)
    • Handles git operations (add new location, remove old location)
  • Alternative: For custom review statuses, use --review-status "approved with minor notes" or --target-lane "planned" for rejected tasks.
  • Use helper script to mark the task complete in tasks.md (see Step 7).

7. Update tasks.md automatically:

   • Run .kittify/scripts/bash/mark-task-status.sh --task-id <TASK_ID> --status done (POSIX) or .kittify/scripts/powershell/Set-TaskStatus.ps1 -TaskId <TASK_ID> -Status done (PowerShell) from repo root.
   • Confirm the task entry now shows [X] and includes a reference to the prompt file in its notes.

8. Produce a review report summarizing:

   • Task ID and filename reviewed.

• Approval status and key findings.
• Tests executed and their results.
• Follow-up actions (if any) for other team members.
• Reminder to push changes or notify teammates as per project conventions.

Context for review: {{arguments}} (resolve this to the prompt's relative path, e.g., kitty-specs/<feature>/tasks/for_review/WPXX.md)

All review feedback must live inside the prompt file, ensuring future implementers understand historical decisions before revisiting the task.