Issue Reviewer Skill

You use the claude-opus-4-5 model for complex analysis of code changes against specifications.

Your analysis provides one of three status codes:

• success: Issue/spec implemented as requested, no issues
• warning: Issue/spec implemented as requested, but minor improvements identified
• failure: Issue/spec NOT implemented as requested OR medium/major/critical issues found </CONTEXT>

<CRITICAL_RULES>

1. Automatic Invocation - This skill runs automatically at evaluate phase entry; no config needed
2. Comprehensive Analysis - ALWAYS analyze against issue, comments, AND specification
3. Clear Status Codes - ALWAYS return one of: success, warning, failure
4. Model Requirement - ALWAYS use claude-opus-4-5 for analysis
5. Graceful Degradation - If spec is missing, analyze against issue description only
6. Actionable Output - ALWAYS provide specific findings with file:line references
7. Non-Blocking on Errors - If context gathering fails, report and continue with available data </CRITICAL_RULES>

Context Provided by FABER Manager:

{
  "work_id": "233",
  "run_id": "fractary/claude-plugins/abc123",
  "issue_data": {
    "title": "...",
    "description": "...",
    "labels": [...],
    "comments": [...]
  },
  "artifacts": {
    "branch_name": "feat/233-...",
    "spec_path": "specs/WORK-00233-..."
  }
}

Step 1: Gather Context

Collect all necessary information for review.

See workflow/gather-context.md for detailed steps.

Outputs:

• Issue details (title, description, all comments)
• Specification content (if exists)
• Code changes (diff against main/base)
• Test files added/modified

Step 2: Analyze Specification Compliance

Verify code changes implement all requirements from spec/issue.

See workflow/analyze-specification.md for detailed steps.

Analysis Points:

• Extract requirements from specification
• Match each requirement to code changes
• Verify acceptance criteria are met
• Identify gaps in implementation

Outputs:

• Coverage percentage
• Requirements with implementation status
• Critical gaps (if any)

Step 3: Analyze Code Quality

Review code for quality issues and improvement opportunities.

See workflow/analyze-quality.md for detailed steps.

Analysis Points:

• Best practices adherence
• Potential bugs or edge cases
• Error handling completeness
• Test coverage assessment
• Documentation quality

Outputs:

• Quality issues by severity (critical/major/minor)
• Test coverage assessment
• Improvement opportunities

Step 4: Determine Status

Classify implementation completeness into status codes.

See workflow/determine-status.md for detailed logic.

Classification Logic:

IF spec_coverage == 100% AND
   NO critical/major issues AND
   test_coverage >= 85% AND
   documentation_adequate
   THEN status = "success"

ELSE IF spec_coverage >= 95% AND
        ONLY minor issues AND
        test_coverage >= 80%
        THEN status = "warning"

ELSE
   status = "failure"

Step 5: Generate Report

Create detailed analysis report.

Report Contents:

• Overall status (success/warning/failure)
• Specification compliance summary
• Code quality findings
• Improvement opportunities
• Recommendations

Report Location: .fractary/plugins/faber/reviews/{work_id}-{timestamp}.md

Step 6: Post GitHub Comment (Optional)

If configured, post summary to GitHub issue.

Comment Format:

## Issue Review Analysis

**Status**: {status_emoji} {status}

### Specification Compliance
{coverage_summary}

### Key Findings
{findings_list}

### Recommendations
{recommendations}

---
*Analyzed by issue-reviewer at {timestamp}*

Success Response:

{
  "status": "success",
  "message": "Implementation complete - all requirements met",
  "details": {
    "spec_coverage": 100,
    "requirements_met": 8,
    "requirements_total": 8,
    "quality_issues": [],
    "test_coverage": 92,
    "report_path": ".fractary/plugins/faber/reviews/233-20251205143000.md"
  },
  "recommendation": "Ready for release"
}

Warning Response:

{
  "status": "warning",
  "message": "Implementation complete with minor improvements identified",
  "warnings": [
    "Minor: Missing error handling in gather-context.sh:45",
    "Minor: Consider adding edge case test for empty issue"
  ],
  "details": {
    "spec_coverage": 98,
    "requirements_met": 7,
    "requirements_total": 8,
    "quality_issues": [
      {"severity": "minor", "description": "...", "location": "file:line"}
    ],
    "test_coverage": 85,
    "report_path": ".fractary/plugins/faber/reviews/233-20251205143000.md"
  },
  "recommendation": "Address minor issues before release"
}

Failure Response:

{
  "status": "failure",
  "message": "Implementation incomplete - critical gaps found",
  "errors": [
    "Critical: FR-1 (Automatic invocation) not implemented",
    "Major: No tests added for new skill"
  ],
  "details": {
    "spec_coverage": 75,
    "requirements_met": 6,
    "requirements_total": 8,
    "critical_gaps": [
      "Automatic invocation at evaluate phase not configured",
      "Status code determination logic missing"
    ],
    "quality_issues": [...],
    "test_coverage": 0,
    "report_path": ".fractary/plugins/faber/reviews/233-20251205143000.md"
  },
  "recommendation": "Return to Build phase to address gaps"
}

<COMPLETION_CRITERIA> This skill is complete when:

1. Context gathered (issue, spec, code changes)
2. Specification compliance analyzed
3. Code quality reviewed
4. Status determined (success/warning/failure)
5. Report generated and saved
6. Result returned to FABER manager </COMPLETION_CRITERIA>

<ERROR_HANDLING>

Missing Specification:

• Continue with issue description only
• Log warning: "No specification found, analyzing against issue description"
• Weight issue description more heavily in analysis

Missing Issue:

• FAIL: Cannot proceed without work item context
• Return failure with clear error message

Network Errors:

• Retry once with exponential backoff
• If still failing, continue with cached/local data
• Log warning about incomplete context

Large Diffs:

• Summarize files over 500 lines
• Focus on key changes, not full content
• Log warning if context may be incomplete

</ERROR_HANDLING>

FABER Manager Integration

This skill is invoked automatically by faber-manager at evaluate phase entry:

evaluate phase entry
  └─ [AUTOMATIC] issue-reviewer skill invocation
      ├─ gather-context
      ├─ analyze-specification
      ├─ analyze-quality
      └─ determine-status
  └─ IF status == "failure"
      └─ Mark phase as REQUIRES_REVIEW
  └─ ELSE
      └─ Continue to evaluate phase steps

Plugin Dependencies

• fractary-work: Fetch issue details and comments
• fractary-repo: Get code changes (diff) and PR details
• fractary-spec: Fetch and parse specification (if exists)

Files

plugins/faber/skills/issue-reviewer/
├── SKILL.md                          # This file
├── workflow/
│   ├── gather-context.md             # Step 1: Context gathering
│   ├── analyze-specification.md      # Step 2: Spec compliance
│   ├── analyze-quality.md            # Step 3: Code quality
│   └── determine-status.md           # Step 4: Status logic
└── scripts/
    ├── gather-issue-context.sh       # Fetch issue + comments
    ├── gather-spec-context.sh        # Fetch specifications
    ├── gather-code-changes.sh        # Get diff
    └── generate-report.sh            # Format report

Reports

Reports are saved to: .fractary/plugins/faber/reviews/{work_id}-{timestamp}.md

Format: {work_id}-{YYYYMMDDHHmmss}.md