======================
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:

.. code-block:: text

   /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-block:: markdown

   # 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:

.. code-block:: python

   # 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:**

.. code-block:: python

   # 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:**

.. code-block:: text

   > 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