# v1.5 Update
Release Date: 2026-01
## Overview
v1.5 adds the QUALITY_REVIEW phase. After garbage detection in PRE_COMMIT, a quality check is performed based on `quality_review.md`, looping until all issues are resolved.
## Background
In flows up to v1.4, merge_to_base was called immediately after PRE_COMMIT garbage detection. However, several issues remained:
| Issue | Impact |
|-------|--------|
| No quality check | Debug code, unused imports, style violations go unnoticed |
| No re-check after fixes | Secondary issues from fixes are not detected |
| No project-specific rules | CLAUDE.md compliance is not verified |
## Design Principles
### Pre-Commit Quality Assurance
| Phase | Responsibility | Check Content |
|-------|---------------|---------------|
| PRE_COMMIT | Garbage detection | Debug logs, commented code, unrelated changes |
| QUALITY_REVIEW | Quality check | Code quality, convention compliance, best practices |
### Revert-to-READY Quality Assurance
When issues are found in quality review, **revert to READY phase for fixes, then re-traverse all phases**. Small fixes within QUALITY_REVIEW are not allowed.
```
[PRE_COMMIT complete] → [QUALITY_REVIEW]
↓
Execute quality_review.md
↓
┌─────────┴─────────┐
↓ ↓
[Issues found] [No issues]
↓ ↓
submit_quality_review merge_to_base
(issues_found=true)
↓
[READY] ← Revert
↓
Apply fixes
↓
[POST_IMPL_VERIFY] → [PRE_COMMIT] → [QUALITY_REVIEW]
```
**Design Rationale:**
- Quality review often catches significant oversights
- Fixes should re-traverse verification (POST_IMPL_VERIFY) and garbage detection (PRE_COMMIT)
- Prevents regressions from incomplete fixes
---
## New Features
### 1. QUALITY_REVIEW Phase
A phase that performs quality checks after PRE_COMMIT and before merge.
#### Phase Transitions
| From | To | Condition |
|------|-----|-----------|
| PRE_COMMIT | QUALITY_REVIEW | finalize_changes complete |
| QUALITY_REVIEW | READY | Issues found (revert) |
| QUALITY_REVIEW | (complete) | submit_quality_review(issues_found=false) |
#### Workflow
```
1. After finalize_changes, transition to QUALITY_REVIEW
2. Read quality_review.md and follow instructions
3. When issues found:
- submit_quality_review(issues_found=true, issues=[...])
- Revert to READY phase
- Fix the issues
- Re-traverse POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW
4. When no issues:
- submit_quality_review(issues_found=false)
- Proceed to merge_to_base
```
**Important:** Edit/Write is forbidden in QUALITY_REVIEW phase. Fixes must be done in READY.
#### Check Content (defined in quality_review.md)
| Category | Check Items |
|----------|-------------|
| Code Quality | Unused imports, dead code, duplicate code |
| Conventions | CLAUDE.md rules, naming conventions, file structure |
| Security | Hardcoded values, sensitive information, vulnerable patterns |
| Performance | N+1 queries, unnecessary loops, memory leaks |
### 2. submit_quality_review Tool
A tool to report quality review results.
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| issues_found | bool | Yes | Whether issues were found |
| issues | array | No | List of found issues (required when issues_found=true) |
| notes | string | No | Additional comments |
#### Response (issues found → Revert to READY)
```json
{
"success": true,
"issues_found": true,
"issues": [
"Unused import 'os' in service.py:3",
"Naming convention violation: getUserData should be get_user_data in utils.py:45",
"Missing error handling in api/handler.py:78"
],
"next_action": "Fix the issues in READY phase, then re-run verification",
"phase": "READY",
"message": "Reverted to READY phase. Fix issues and proceed through POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW."
}
```
#### Response (no issues)
```json
{
"success": true,
"issues_found": false,
"message": "Quality review passed. Ready for merge.",
"next_action": "Call merge_to_base to complete"
}
```
### 3. --no-quality Flag
A flag to skip quality review.
#### Usage
```bash
# Standard mode (with quality review)
/code fix this bug
# Skip quality review
/code --no-quality fix this typo
```
#### Behavior
When `--no-quality` is specified, merge_to_base becomes available directly after PRE_COMMIT.
**Note:** `--quick` mode also skips QUALITY_REVIEW (no branch, no garbage detection, so quality review is unnecessary).
#### Phase Matrix (Quality Review Related)
| Option | Explore | Implement | Verify | Garbage | Quality | Branch |
|--------|:-------:|:---------:|:------:|:-------:|:-------:|:------:|
| (default) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `--no-quality` | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| `--quick` / `-q` | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
---
## New Tools
### submit_quality_review
Report quality review results.
#### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| issues_found | bool | Yes | - | Whether issues were found |
| issues | array | No | [] | List of found issues (required when issues_found=true) |
| notes | string | No | null | Additional comments |
#### Usage Examples
**When issues found (Revert to READY):**
```
mcp__code-intel__submit_quality_review
issues_found: true
issues: [
"Unused import 'os' in auth/service.py:3",
"console.log left in auth/service.js:45",
"Missing type hints in validate_user function"
]
```
→ Reverts to READY phase, fix issues, then re-traverse POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW
**When no issues:**
```
mcp__code-intel__submit_quality_review
issues_found: false
notes: "All checks passed"
```
→ merge_to_base becomes available
---
## New Prompt Files
### .code-intel/review_prompts/quality_review.md
A prompt file that defines quality review instructions.
#### Default Content
```markdown
# Quality Review Checklist
Review the changes and check for the following issues:
## Code Quality
- [ ] No unused imports
- [ ] No dead code or unreachable statements
- [ ] No duplicate code that should be extracted
- [ ] Proper error handling
## Conventions
- [ ] Follows project naming conventions
- [ ] Matches existing code style
- [ ] Follows CLAUDE.md rules
## Security
- [ ] No hardcoded secrets or credentials
- [ ] No sensitive data in logs
- [ ] Input validation where needed
## Performance
- [ ] No obvious N+1 queries
- [ ] No unnecessary loops or iterations
- [ ] Efficient data structures used
## Action
**If issues found:**
1. List all issues with file:line references
2. Report with submit_quality_review(issues_found=true, issues=[...])
3. You will be reverted to READY phase
4. Fix the issues, then proceed through POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW
**If no issues:**
1. Report with submit_quality_review(issues_found=false)
2. Proceed to merge_to_base
**Important:** Do NOT fix issues in QUALITY_REVIEW phase. Always report first, then fix in READY phase.
```
---
## Flow Changes
### Before (v1.4)
```
Step 10: PRE_COMMIT
├─ review_changes
└─ finalize_changes
↓
Step 11: merge_to_base
```
### After (v1.5)
```
Step 10: PRE_COMMIT
├─ review_changes
└─ finalize_changes
↓
Step 10.5: QUALITY_REVIEW ← NEW
├─ Execute quality_review.md
├─ Issues found → submit_quality_review(issues_found=true) → Revert to READY
│ → Fix → POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW
└─ No issues → submit_quality_review(issues_found=false)
↓
Step 11: merge_to_base
```
---
## Skill Prompt Changes
### Step 10.5: Quality Review (New)
```markdown
## Step 10.5: Quality Review
**Post-PRE_COMMIT, pre-merge quality check.**
1. Read `.code-intel/review_prompts/quality_review.md`
2. Review changes following the checklist
3. When issues found:
- List all issues with file:line references
- Report with submit_quality_review(issues_found=true, issues=[...])
- You will be reverted to READY phase
- Fix the issues
- Re-traverse POST_IMPL_VERIFY → PRE_COMMIT → QUALITY_REVIEW
4. When no issues:
- Report with submit_quality_review(issues_found=false)
- Proceed to merge_to_base
**Important:** Fixes are forbidden in QUALITY_REVIEW. Always report → revert → fix in READY.
**Skip conditions:**
- `--no-quality` flag specified
```
---
## Configuration
`.code-intel/context.yml`:
```yaml
quality_review:
enabled: true # Enable quality review (default: true)
prompt_file: "review_prompts/quality_review.md"
max_revert_count: 3 # Max READY revert count (prevents infinite loops)
```
---
## Error Handling
### max_revert_count Exceeded
When revert count exceeds `max_revert_count`, force completion and proceed to `merge_to_base`.
```json
{
"success": true,
"issues_found": true,
"forced_completion": true,
"message": "Max revert count (3) exceeded. Forcing completion.",
"warning": "Quality issues may remain unresolved.",
"next_action": "Call merge_to_base to complete"
}
```
**Design Rationale:** Prevents infinite loops while allowing task completion. Quality issues may remain, but user can address them later.
### quality_review.md Not Found
When prompt file doesn't exist, emit warning and skip QUALITY_REVIEW phase, proceeding directly to `merge_to_base`.
```json
{
"success": true,
"skipped": true,
"warning": "quality_review.md not found at .code-intel/review_prompts/quality_review.md",
"message": "Quality review skipped. Proceeding to merge.",
"next_action": "Call merge_to_base to complete"
}
```
**Design Rationale:** Quality review cannot execute without prompt file. Prevents task blocking during migration or file loss scenarios.
---
## Command Options
| Long | Short | Description |
|------|-------|-------------|
| `--no-quality` | - | Skip quality review |
---
## Breaking Changes
| Change | Impact | Resolution |
|--------|--------|------------|
| QUALITY_REVIEW phase added | Auto-transition after finalize_changes | Place quality_review.md |
| merge_to_base prerequisite | QUALITY_REVIEW completion required | Call submit_quality_review |
---
## Migration
1. Create `.code-intel/review_prompts/quality_review.md`
2. Update Skill prompt (code.md)
3. Add `--no-quality` flag recognition
---
## Implementation Checklist
### QUALITY_REVIEW Phase
- [ ] Phase transition logic (PRE_COMMIT → QUALITY_REVIEW)
- [ ] QUALITY_REVIEW → READY revert logic
- [ ] Skip with `--no-quality` flag
- [ ] Max revert count limit (max_revert_count)
### submit_quality_review Tool
- [ ] Parameters: `issues_found`, `issues`, `notes`
- [ ] Revert to READY when `issues_found=true`
- [ ] Allow merge_to_base when `issues_found=false`
- [ ] Revert counter management
### Prompt Files
- [ ] Create `quality_review.md` template
- [ ] Auto-placement in init-project.sh
### Error Handling
- [ ] Force completion when max_revert_count exceeded
- [ ] Warning and skip when quality_review.md missing
### Tests
- [ ] submit_quality_review normal case (no issues)
- [ ] submit_quality_review revert (issues → READY → fix → re-traverse → no issues)
- [ ] --no-quality flag skip
- [ ] Max revert count exceeded forced completion
- [ ] quality_review.md missing skip
