# Manage Coding AI

Three stages: Plan -> Code -> Review

## Stage 1: Plan

1. Deeply understand the feature we are trying to add or fix. When human guidance is unclear, ask clarifying questions to truly understand the real requirements. Review entire codebase, closely following how data will flow and get transformed by code logic, to truly deeply understand how the codebase works, then plan out the best way to structure the code changes. Search the web to find best modern practices when needed.
1. Write the specification as a ticket in tools/tickets. Mark the ticket that this pull request is working on by prefixing the filename with `ACTIVE-` string. The document must be comprehensive such that even an intern can understand what must be done, for what reason, how the codebase works now, how the codebase must be changed. Describe the big picture at the product level (what the product does, and what the code change will enable), how the codebase works at the big picture (how it works now, and how it must be changed to work), and then get down to the specific details. Specific details are very important. You must plan out the tasks such that the ordering enables unblocking. Pay attention to the sequence of dependencies. You must decompose large complex tasks into small simple tasks that can be standalone commits. Each task must be simple enough for an intern to accomplish, and be tested as a standalone increment. Finally, you must write out the guardrails and constraints such that the way the feature works is as intended by the vision and not in a hacky or wrong way. Document must be at most 3000 words. Write this out as a document. Do not proceed to coding without human approval. Do not write details unnecessary for code changes, such as timeline, or documentation instructions.
1. Set up repomix context using repomixignore. The repomix-output file must contain all files relevant to best understanding the codebase.
1. Ticket must only include technical discussions. It must NOT include management details such as timeline, time cost.

### Setup Repomix Context

```bash
# Reset to ignore everything
echo "*" > .repomixignore

# Include files relevant to this pull request
echo "!path/to/an/important/file.ts" >> .repomixignore

# Include files they rely on only if implementation details matter. If only input and output matter, infer based on usage in the file we did include.
```

## Stage 2: Code

Code and pass the tests.

- Keep updating repomixignore to include relevant files.
- Keep checking guidelines in CLAUDE.md.
- Keep cleaning up unnecessary code, especially code that you tried as one approach but ended up abandoning for a different approach.

### When Stuck

1. **Remove Cruft**: Delete unnecessary files and unused code
1. **Update Context**: Add only relevant files to repomixignore
1. **Generate Repomix**: Create focused context file
1. **Call Claude Opus**:
   ```bash
   claude --model opus -p "Review repomix-output.xml and provide solution for [specific issue]."
   ```
1. **Call Gemini Pro**:
   ```bash
   gemini -p "Review @repomix-output.xml. What am I missing? Suggest better approach."
   ```
1. **Compare Solutions**: Take best ideas from both models

## Stage 3: Review

### Use Review Script

```bash
./tools/scripts/review-ai-code.sh
```

### Automated Checks First

```bash
# JavaScript/TypeScript
pnpm quality
pnpm test

# Python (in copilot dir)
uv run ruff check .
uv run black --check .
uv run mypy .
```

### Manual Review Focus

- **Security**: Input validation, XSS prevention, no hardcoded secrets
- **Performance**: Efficient queries, no memory leaks, proper caching
- **Architecture**: Single responsibility, DRY, separation of concerns
- **TypeScript**: No `any` types, proper error handling
- **Python**: Type annotations, proper exception handling
- **Tests**: Comprehensive coverage, edge cases, meaningful assertions

### Issue Reporting Format

```
FILE: path/to/file.ts
LINE: 42
CATEGORY: Security|Performance|Style|Architecture|Testing
SEVERITY: Critical|High|Medium|Low
ISSUE: Brief description
RECOMMENDATION: Specific fix
```

### Multi-Model Final Review

```bash
# Generate repomix with all changes
repomix

# Comprehensive review with both models
claude --model opus -p "Review repomix-output.xml for implementation quality, correctness, security, performance. Focus on changed files and provide specific feedback."

gemini -p "Review @repomix-output.xml for code quality, correctness, security, performance. Examine source files directly and provide line-specific feedback."
```

### Quality Gates

- **Critical (Must Fix)**: Security vulnerabilities, test failures, performance regressions
- **High (Should Fix)**: Code style violations, missing error handling, incomplete tests
- **Medium (Consider)**: Minor optimizations, better naming, additional test coverage

## Scope Limits

- **Target**: Only changed files in PR (< 2000 lines total)
- **Focus**: Modified, added, deleted lines only
- **Exclude**: Unchanged existing codebase

## Success Criteria

- All tests pass
- No linting errors
- Security vulnerabilities addressed
- Performance requirements met
- Code review completed with both AI models