Code Review Response

Code Review Response#

Process manual code review comments marked with ISSUE: prefix into structured reports, extract lessons learned, and clean up the source files.

Description#

This skill finds all ISSUE: comments across your codebase, evaluates whether each represents a genuine issue, generates a structured markdown report with lessons learned for coding standards, and removes the processed ISSUE comments from source files.

Triggers#

The skill activates when you mention:

  • Processing ISSUE comments

  • Code review responses

  • Reviewing code with ISSUE markers

  • Generating code review reports

Explicit invocation:

/wf:code-review-response

Workflow#

  1. Search for issues

    • Grep for ISSUE: in all files

    • Check inline code comments (may span two lines)

    • Check markdown review files

  2. Evaluate each issue

    • Extract the issue description

    • Note file path and line number

    • Read surrounding code context

    • Assess validity (real issue vs false positive)

  3. Generate report

    • Create resources/agent-docs/reviews/code/ directory if needed

    • Determine next file number (code-review-N.md)

    • Write structured report with lessons learned

  4. Clean up source files

    • Remove all processed ISSUE: comments from code files

    • Remove multi-line issue comments completely

    • Delete markdown review files that only contained issues

Issue Evaluation#

For each ISSUE: comment found, the skill assesses:

Valid issues - Problems that should be fixed:

  • Code quality concerns

  • Bug risks

  • Performance issues

  • Style violations

Non-issues - Comments that don’t require action:

  • Intentional design decisions

  • Already handled elsewhere

  • False positives

  • Misunderstandings

Lessons Learned#

After evaluating all issues, the skill identifies patterns and extracts general lessons:

  • Recurring themes - Issues that appear multiple times

  • Knowledge gaps - Areas where coding standards need clarification

  • Best practices - Patterns to document for the team

  • Tooling opportunities - Issues that linters could catch automatically

These lessons are formatted as actionable recommendations that can be fed back into coding standards documentation.

Output Format#

Reports are saved to resources/agent-docs/reviews/code/code-review-N.md:

# Code Review Report

Generated: 2026-02-03

## Summary

- Total issues found: 5
- Valid issues: 3
- Non-issues: 2

## Valid Issues

### Issue 1: Missing error handling

- **File**: `src/processor.py`
- **Line**: 42
- **Comment**: ISSUE: No handling for empty input list
- **Context**: [code snippet]
- **Assessment**: Function will raise IndexError on empty input
- **Suggested approach**: Add early return or validation

## Non-Issues

### Non-Issue 1: Line length

- **File**: `src/utils.py`
- **Line**: 15
- **Comment**: ISSUE: Line too long
- **Reason not an issue**: Line is 82 chars, within project's 88 char limit

## Lessons Learned

### Coding Standards Recommendations

1. **Error Handling**
   - Observation: Multiple functions lack input validation
   - Recommendation: All public functions should validate inputs
   - Example: `if not items: return []`

2. **Type Hints**
   - Observation: Several functions missing return type hints
   - Recommendation: Require type hints for all public APIs

### Suggested Linter Rules

- Enable `ruff` rule `B006` to catch mutable default arguments

### Training Opportunities

- Team workshop on defensive programming patterns

Cleanup Rules#

When removing ISSUE comments:

  • Single-line comments: Delete the entire line

  • Multi-line comments: Delete all continuation lines

  • Inline comments: Remove only the ISSUE portion if other code on the line

  • Markdown files: Delete issue entries; delete file if empty after cleanup

  • Preserve formatting: Maintain surrounding code structure and indentation

Multi-Line Issues#

Issue comments can span two lines:

# ISSUE: This function is too complex and should be
# refactored into smaller units
def complex_function():
    ...

The skill detects continuation lines that start with # and continue the sentence. Both lines are removed during cleanup.

Example Usage#

Adding issues during review:

# ISSUE: Variable name 'x' is not descriptive
x = calculate_total(items)

# ISSUE: This nested loop has O(n^2) complexity, consider
# using a dictionary for O(n) lookup
for item in items:
    for other in others:
        if item.id == other.id:
            process(item, other)

Invoking the skill:

> I've added ISSUE comments during my code review.
> Please process them and generate a report.

Result:

  1. A report at resources/agent-docs/reviews/code/code-review-1.md documenting each issue with assessment, suggested fixes, and lessons learned

  2. The ISSUE: comments are removed from the source files

Integration with Coding Standards#

The lessons learned section is designed to improve your coding standards:

  1. Review the Coding Standards Recommendations section

  2. Add relevant guidelines to your project’s CLAUDE.md or standards docs

  3. Configure suggested linter rules in pyproject.toml

  4. Schedule training sessions for identified knowledge gaps

Integration with the slice loop#

The generated reports feed the slice-loop workflow:

  1. Generate the code review report

  2. Synthesize the findings into a spec with the to-spec skill

  3. Break the spec into slices with to-slices

  4. Work the frontier with implement to land the fixes

Contents