Context Management System

[frankbria]

Summary

Implement systematic context reset mechanisms to prevent quality degradation in long AI conversations.

Problem

Long AI conversations lead to:

• Attention decay on earlier context
• Shortcut patterns reinforcing
• Gradual quality decline
• Loss of architectural understanding

Tasks

1. Context Management Rules

• Define token budget for conversations (~50k)
• Set checkpoint frequency (every 5 responses)
• Establish reset triggers
• Document context handoff process

2. Checkpoint System

• Add mandatory checkpoint every 5 AI responses
• Require full test run at checkpoints
• Require coverage report at checkpoints
• Ask "continue or reset?" at each checkpoint

3. Context Handoff Template

• Create template for summarizing context
• Include: completed features, current state, known issues
• Format for easy copy-paste to new conversation
• Include test/coverage evidence

4. Automated Detection

• Integrate with quality-ratchet.py
• Auto-suggest resets when quality drops
• Track conversation length
• Warn at token budget limits

5. Documentation

• Update .claude/rules.md with context limits
• Document handoff process
• Provide example context summaries
• Explain why resets are necessary

Context Handoff Template

## Context Summary for Continuation

### Completed Features
- Feature A: [status] - tests passing, coverage 85%
- Feature B: [status] - tests passing, coverage 82%

### Current State
- All tests passing: [yes/no]
- Coverage: [XX]%
- Known issues: [list]

### Next Tasks
- [ ] Task 1
- [ ] Task 2

### Test Evidence
[paste pytest output]
[paste coverage report]

Reset Triggers

Automatic context reset recommended when:

1. Quality drops >10% (via quality-ratchet)
2. Response count exceeds 15-20
3. Token budget approaches limit (~45k)
4. AI shows signs of "laziness" (shortcuts, false claims)

Success Criteria

• Context resets happen before quality degrades
• Handoff process is smooth and documented
• Quality remains consistent across resets
• Token budgets are respected

User Experience

• Make resets feel natural, not disruptive
• Provide clear value: "Let's start fresh to maintain quality"
• Template makes handoff painless
• Document the "why" so users buy in

Dependencies

• Issue feat(sprint-4): Multi-Agent Coordination System - P0 & P1 Complete #3 (quality-ratchet) for degradation detection
• Issue Add Claude Code GitHub Workflow #1 (rules.md) to document the policy

Estimated Effort: 2-3 hours

[traycerai]

Plan

Observations

The CodeFRAME project has a well-established structure with:

• .claude/ directory for AI assistant configuration (settings, commands)
• scripts/ directory for utility scripts (health checks, deployment, verification)
• .specify/ directory for feature specification workflow
• Comprehensive testing infrastructure with pytest, coverage tracking (85% threshold)
• Token usage tracking already implemented in AnthropicProvider and LeadAgent
• Constitution-based governance with semantic versioning
• No existing quality-ratchet.py or .claude/rules.md files

The issue requests a meta-level context management system for AI conversations (not agent context management from Sprint 7). This is about preventing quality degradation in long human-AI conversations through checkpoints, resets, and handoff templates.

Approach

Implement a Context Management System with four main components:

1. .claude/rules.md - Document context management policies (token budgets, checkpoint frequency, reset triggers)
2. scripts/quality-ratchet.py - Python script to monitor conversation quality and suggest resets
3. Context handoff template - Embedded in rules.md for easy copy-paste
4. Integration documentation - Update CLAUDE.md to reference the new workflow

The script will be standalone (no runtime integration) and designed for manual execution or future automation. It will parse conversation logs/metrics and emit warnings based on configurable thresholds.

Reasoning

I explored the repository structure, examined existing .claude/ configuration, reviewed token tracking implementation in the codebase, studied the project's constitution and governance model, analyzed testing and quality infrastructure, and confirmed no existing quality-ratchet or rules files exist.

Proposed File Changes

📄 .claude/rules.md ^(NEW) 🔗

References

• 📄 .specify/memory/constitution.md
• 📄 codeframe/providers/anthropic.py
• 📄 .coveragerc

Create a comprehensive context management rules document that defines:

Structure:

• Document header with version and last updated date
• Overview section explaining the purpose (prevent quality degradation in long AI conversations)
• Token Budget section defining the ~50k token limit for conversations
• Checkpoint System section detailing the every-5-responses checkpoint requirement
• Reset Triggers section listing automatic reset conditions (quality drop >10%, response count >15-20, token budget >45k, AI laziness signs)
• Context Handoff Process section with step-by-step instructions
• Context Handoff Template section (embedded markdown template for easy copy-paste)

Content Details:

1. Token Budget Rules:

   • Define 50,000 token soft limit for conversations
   • Explain token counting methodology (input + output tokens)
   • Reference existing token tracking in codeframe/providers/anthropic.py (lines 108-110)
   • Warning threshold at 45,000 tokens (90%)

2. Checkpoint System:

   • Mandatory checkpoint every 5 AI responses
   • Required actions at each checkpoint: run full test suite, generate coverage report, ask "continue or reset?"
   • Checkpoint template with sections for: response count, token usage, test status, coverage percentage, quality indicators

3. Reset Triggers:

   • Automatic: Quality drop >10% (detected by quality-ratchet.py), token budget >90%, response count >20
   • Manual: User discretion, AI showing shortcuts/false claims, loss of architectural understanding
   • Integration point with Issue feat(sprint-4): Multi-Agent Coordination System - P0 & P1 Complete #3 (quality-ratchet.py)

4. Context Handoff Template:
   Include a complete markdown template with sections:

   • Completed Features (with test status and coverage)
   • Current State (all tests passing, coverage %, known issues)
   • Next Tasks (prioritized checklist)
   • Test Evidence (pytest output, coverage report)
   • Architecture Notes (key decisions, patterns established)
   • Dependencies (external services, libraries, versions)

5. Best Practices:

   • When to reset vs continue
   • How to maintain quality across resets
   • Tips for effective handoffs
   • Common pitfalls to avoid

Format: Use markdown with clear headings, code blocks for templates, and reference existing project conventions from .specify/memory/constitution.md

📄 scripts/quality-ratchet.py ^(NEW) 🔗

References

• 📄 pyproject.toml
• 📄 scripts/verify_migration_001.py
• 📄 codeframe/providers/anthropic.py

Create a Python script to monitor conversation quality and suggest context resets. This script implements the automated detection requirements from Issue #17.

Script Structure:

1. Imports and Configuration:

   • Standard library: argparse, json, sys, pathlib, datetime
   • Type hints for clarity
   • Configuration constants (TOKEN_BUDGET=50000, WARNING_THRESHOLD=45000, MAX_RESPONSES=20, QUALITY_DROP_THRESHOLD=0.10)

2. Data Models (using dataclasses or Pydantic):

   • ConversationMetrics: response_count, total_tokens, input_tokens, output_tokens, quality_score, timestamp
   • QualityReport: status (OK/WARNING/CRITICAL), message, recommendations, metrics

3. Core Functions:

   a. load_metrics(input_file: Path) -> ConversationMetrics

   • Parse JSON input file with conversation metrics
   • Support multiple input formats (manual JSON, log parsing)
   • Validate required fields

   b. calculate_quality_score(metrics: ConversationMetrics, baseline: float) -> float

   • Placeholder for future integration with Issue feat(sprint-4): Multi-Agent Coordination System - P0 & P1 Complete #3
   • Currently returns 1.0 (no degradation) or accepts manual input
   • Document expected quality metric sources

   c. check_token_budget(metrics: ConversationMetrics) -> tuple[str, str]

   • Return (status, message) based on token usage
   • OK: <45k tokens, WARNING: 45k-50k, CRITICAL: >50k

   d. check_response_count(metrics: ConversationMetrics) -> tuple[str, str]

   • Return (status, message) based on response count
   • OK: <15, WARNING: 15-20, CRITICAL: >20

   e. check_quality_degradation(current: float, baseline: float) -> tuple[str, str]

   • Compare current quality score to baseline
   • CRITICAL if drop >10%

   f. generate_report(metrics: ConversationMetrics, baseline_quality: float) -> QualityReport

   • Aggregate all checks
   • Determine overall status (worst of all checks)
   • Generate actionable recommendations

   g. format_output(report: QualityReport, format: str) -> str

   • Support JSON and human-readable formats
   • Include color coding for terminal output (using colorama or rich)

4. CLI Interface (using argparse):

   • --input FILE: Path to metrics JSON file (required)
   • --baseline-quality FLOAT: Baseline quality score (default: 1.0)
   • --format {json,text}: Output format (default: text)
   • --config FILE: Optional config file for custom thresholds
   • --verbose: Enable detailed output

5. Example Metrics Input Format:

   {
     "response_count": 12,
     "total_tokens": 38500,
     "input_tokens": 25000,
     "output_tokens": 13500,
     "quality_score": 0.92,
     "timestamp": "2025-01-19T10:30:00Z"
   }

6. Output Examples:

   • Text format: Colored status indicators, clear recommendations, checkpoint reminder
   • JSON format: Structured data for automation/integration

7. Integration Points:

   • Document how to collect metrics (manual tracking, log parsing, future automation)
   • Reference token tracking in codeframe/providers/anthropic.py
   • Note dependency on Issue feat(sprint-4): Multi-Agent Coordination System - P0 & P1 Complete #3 for quality score calculation
   • Suggest future integration with .claude/commands/ for automated checks

8. Error Handling:

   • Graceful handling of missing/invalid input files
   • Clear error messages for validation failures
   • Exit codes: 0=OK, 1=WARNING, 2=CRITICAL, 3=ERROR

Style: Follow project conventions from pyproject.toml (Black formatting, type hints, 100 char line length). Include comprehensive docstrings and inline comments. Add shebang for direct execution.

📄 CLAUDE.md ^(MODIFY) 🔗

Update the development guidelines to reference the new context management system.

Changes to make:

1. Add new section after "Recent Changes" (around line 55):

   ## Context Management for AI Conversations
   
   To maintain quality in long AI conversations, follow the context management rules:
   - **Token Budget**: ~50k tokens per conversation (see `.claude/rules.md`)
   - **Checkpoints**: Every 5 AI responses, run tests and ask "continue or reset?"
   - **Quality Monitoring**: Use `scripts/quality-ratchet.py` to detect degradation
   - **Context Handoff**: Use template in `.claude/rules.md` when starting new conversations
   
   See [.claude/rules.md](.claude/rules.md) for complete guidelines.

2. Update "Commands" section (around line 37-43):
   Add reference to quality monitoring:

   # Quality monitoring
   python scripts/quality-ratchet.py --input metrics.json  # Check conversation health

3. Add to "Documentation Navigation" section (around line 6-13):
   Add .claude/rules.md to the quick reference list:

   - **Context management**: [.claude/rules.md](.claude/rules.md) (AI conversation quality)

Rationale: CLAUDE.md is the primary AI assistant development guidelines document (line 1-2), so it should reference the new context management workflow. The changes are minimal and non-disruptive, following the existing structure and style.

📄 scripts/quality-ratchet-example.json ^(NEW) 🔗

Create an example metrics input file for the quality-ratchet.py script to demonstrate usage.

Content:

{
  "response_count": 12,
  "total_tokens": 38500,
  "input_tokens": 25000,
  "output_tokens": 13500,
  "quality_score": 0.92,
  "timestamp": "2025-01-19T10:30:00Z",
  "conversation_id": "example-conversation",
  "notes": "Example metrics file for quality-ratchet.py. Replace with actual conversation metrics."
}

Purpose:

• Provide a concrete example for users
• Document the expected input format
• Enable quick testing of the quality-ratchet.py script
• Serve as a template for manual metric tracking

Usage Documentation:
Include a comment block at the top explaining:

• How to collect these metrics manually
• How to run the script with this file
• What each field represents
• Future automation possibilities

📄 README.md ^(MODIFY) 🔗

Add a brief mention of the context management system in the documentation section.

Change location: In the "Documentation" section (around line 659-698), add a new subsection under "Project-Wide Documentation":

#### AI Development Workflow
- **[.claude/rules.md](.claude/rules.md)** - Context management for AI conversations
- **[scripts/quality-ratchet.py](scripts/quality-ratchet.py)** - Conversation quality monitoring

Rationale: The README.md already has a comprehensive documentation section (lines 659-698) that lists all major documentation files. Adding the new context management files here ensures discoverability. The placement under "Project-Wide Documentation" is appropriate since this is a meta-level development process, not a feature of the CodeFRAME system itself.

Style: Follow the existing format with bold file paths and brief descriptions, consistent with other entries in the documentation section.

Diagram

sequenceDiagram
    participant Dev as Developer
    participant AI as AI Assistant
    participant Script as quality-ratchet.py
    participant Rules as .claude/rules.md
    
    Note over Dev,AI: Long Conversation in Progress
    
    loop Every 5 Responses
        AI->>Dev: Response #5, #10, #15...
        Dev->>Dev: Run full test suite
        Dev->>Dev: Generate coverage report
        Dev->>Script: Check conversation health
        Script->>Script: Analyze metrics<br/>(tokens, responses, quality)
        
        alt Metrics OK
            Script-->>Dev: ✅ Status: OK<br/>Continue conversation
            Dev->>AI: Continue with next task
        else Warning Threshold
            Script-->>Dev: ⚠️ WARNING<br/>Approaching limits
            Dev->>Dev: Review quality indicators
            Dev->>Rules: Check reset criteria
            
            alt Quality Still Good
                Dev->>AI: Continue (monitored)
            else Quality Degrading
                Dev->>Rules: Use handoff template
                Dev->>Dev: Copy context summary
                Dev->>AI: [NEW CONVERSATION]<br/>Paste handoff context
            end
        else Critical Threshold
            Script-->>Dev: 🚨 CRITICAL<br/>Reset recommended
            Dev->>Rules: Use handoff template
            Dev->>Dev: Prepare context summary<br/>(features, tests, coverage)
            Dev->>AI: [NEW CONVERSATION]<br/>Paste handoff context
            AI->>Dev: Resume with fresh context
        end
    end
    
    Note over Dev,AI: Quality Maintained Across Resets

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The CodeFRAME project has a well-established structure with:
- `.claude/` directory for AI assistant configuration (settings, commands)
- `scripts/` directory for utility scripts (health checks, deployment, verification)
- `.specify/` directory for feature specification workflow
- Comprehensive testing infrastructure with pytest, coverage tracking (85% threshold)
- Token usage tracking already implemented in `AnthropicProvider` and `LeadAgent`
- Constitution-based governance with semantic versioning
- No existing `quality-ratchet.py` or `.claude/rules.md` files

The issue requests a **meta-level** context management system for AI conversations (not agent context management from Sprint 7). This is about preventing quality degradation in long human-AI conversations through checkpoints, resets, and handoff templates.

### Approach

Implement a Context Management System with four main components:

1. **`.claude/rules.md`** - Document context management policies (token budgets, checkpoint frequency, reset triggers)
2. **`scripts/quality-ratchet.py`** - Python script to monitor conversation quality and suggest resets
3. **Context handoff template** - Embedded in rules.md for easy copy-paste
4. **Integration documentation** - Update CLAUDE.md to reference the new workflow

The script will be standalone (no runtime integration) and designed for manual execution or future automation. It will parse conversation logs/metrics and emit warnings based on configurable thresholds.

### Reasoning

I explored the repository structure, examined existing `.claude/` configuration, reviewed token tracking implementation in the codebase, studied the project's constitution and governance model, analyzed testing and quality infrastructure, and confirmed no existing quality-ratchet or rules files exist.

## Mermaid Diagram

sequenceDiagram
    participant Dev as Developer
    participant AI as AI Assistant
    participant Script as quality-ratchet.py
    participant Rules as .claude/rules.md
    
    Note over Dev,AI: Long Conversation in Progress
    
    loop Every 5 Responses
        AI->>Dev: Response #5, #10, #15...
        Dev->>Dev: Run full test suite
        Dev->>Dev: Generate coverage report
        Dev->>Script: Check conversation health
        Script->>Script: Analyze metrics<br/>(tokens, responses, quality)
        
        alt Metrics OK
            Script-->>Dev: ✅ Status: OK<br/>Continue conversation
            Dev->>AI: Continue with next task
        else Warning Threshold
            Script-->>Dev: ⚠️ WARNING<br/>Approaching limits
            Dev->>Dev: Review quality indicators
            Dev->>Rules: Check reset criteria
            
            alt Quality Still Good
                Dev->>AI: Continue (monitored)
            else Quality Degrading
                Dev->>Rules: Use handoff template
                Dev->>Dev: Copy context summary
                Dev->>AI: [NEW CONVERSATION]<br/>Paste handoff context
            end
        else Critical Threshold
            Script-->>Dev: 🚨 CRITICAL<br/>Reset recommended
            Dev->>Rules: Use handoff template
            Dev->>Dev: Prepare context summary<br/>(features, tests, coverage)
            Dev->>AI: [NEW CONVERSATION]<br/>Paste handoff context
            AI->>Dev: Resume with fresh context
        end
    end
    
    Note over Dev,AI: Quality Maintained Across Resets

## Proposed File Changes

### .claude/rules.md(NEW)

References: 

- .specify/memory/constitution.md
- codeframe/providers/anthropic.py
- .coveragerc

Create a comprehensive context management rules document that defines:

**Structure:**
- Document header with version and last updated date
- Overview section explaining the purpose (prevent quality degradation in long AI conversations)
- Token Budget section defining the ~50k token limit for conversations
- Checkpoint System section detailing the every-5-responses checkpoint requirement
- Reset Triggers section listing automatic reset conditions (quality drop >10%, response count >15-20, token budget >45k, AI laziness signs)
- Context Handoff Process section with step-by-step instructions
- Context Handoff Template section (embedded markdown template for easy copy-paste)

**Content Details:**

1. **Token Budget Rules:**
   - Define 50,000 token soft limit for conversations
   - Explain token counting methodology (input + output tokens)
   - Reference existing token tracking in `codeframe/providers/anthropic.py` (lines 108-110)
   - Warning threshold at 45,000 tokens (90%)

2. **Checkpoint System:**
   - Mandatory checkpoint every 5 AI responses
   - Required actions at each checkpoint: run full test suite, generate coverage report, ask "continue or reset?"
   - Checkpoint template with sections for: response count, token usage, test status, coverage percentage, quality indicators

3. **Reset Triggers:**
   - Automatic: Quality drop >10% (detected by quality-ratchet.py), token budget >90%, response count >20
   - Manual: User discretion, AI showing shortcuts/false claims, loss of architectural understanding
   - Integration point with Issue #3 (quality-ratchet.py)

4. **Context Handoff Template:**
   Include a complete markdown template with sections:
   - Completed Features (with test status and coverage)
   - Current State (all tests passing, coverage %, known issues)
   - Next Tasks (prioritized checklist)
   - Test Evidence (pytest output, coverage report)
   - Architecture Notes (key decisions, patterns established)
   - Dependencies (external services, libraries, versions)

5. **Best Practices:**
   - When to reset vs continue
   - How to maintain quality across resets
   - Tips for effective handoffs
   - Common pitfalls to avoid

**Format:** Use markdown with clear headings, code blocks for templates, and reference existing project conventions from `.specify/memory/constitution.md`

### scripts/quality-ratchet.py(NEW)

References: 

- pyproject.toml
- scripts/verify_migration_001.py
- codeframe/providers/anthropic.py

Create a Python script to monitor conversation quality and suggest context resets. This script implements the automated detection requirements from Issue #17.

**Script Structure:**

1. **Imports and Configuration:**
   - Standard library: argparse, json, sys, pathlib, datetime
   - Type hints for clarity
   - Configuration constants (TOKEN_BUDGET=50000, WARNING_THRESHOLD=45000, MAX_RESPONSES=20, QUALITY_DROP_THRESHOLD=0.10)

2. **Data Models (using dataclasses or Pydantic):**
   - ConversationMetrics: response_count, total_tokens, input_tokens, output_tokens, quality_score, timestamp
   - QualityReport: status (OK/WARNING/CRITICAL), message, recommendations, metrics

3. **Core Functions:**

   a. `load_metrics(input_file: Path) -> ConversationMetrics`
      - Parse JSON input file with conversation metrics
      - Support multiple input formats (manual JSON, log parsing)
      - Validate required fields

   b. `calculate_quality_score(metrics: ConversationMetrics, baseline: float) -> float`
      - Placeholder for future integration with Issue #3
      - Currently returns 1.0 (no degradation) or accepts manual input
      - Document expected quality metric sources

   c. `check_token_budget(metrics: ConversationMetrics) -> tuple[str, str]`
      - Return (status, message) based on token usage
      - OK: <45k tokens, WARNING: 45k-50k, CRITICAL: >50k

   d. `check_response_count(metrics: ConversationMetrics) -> tuple[str, str]`
      - Return (status, message) based on response count
      - OK: <15, WARNING: 15-20, CRITICAL: >20

   e. `check_quality_degradation(current: float, baseline: float) -> tuple[str, str]`
      - Compare current quality score to baseline
      - CRITICAL if drop >10%

   f. `generate_report(metrics: ConversationMetrics, baseline_quality: float) -> QualityReport`
      - Aggregate all checks
      - Determine overall status (worst of all checks)
      - Generate actionable recommendations

   g. `format_output(report: QualityReport, format: str) -> str`
      - Support JSON and human-readable formats
      - Include color coding for terminal output (using colorama or rich)

4. **CLI Interface (using argparse):**
   - `--input FILE`: Path to metrics JSON file (required)
   - `--baseline-quality FLOAT`: Baseline quality score (default: 1.0)
   - `--format {json,text}`: Output format (default: text)
   - `--config FILE`: Optional config file for custom thresholds
   - `--verbose`: Enable detailed output

5. **Example Metrics Input Format:**
   ```json
   {
     "response_count": 12,
     "total_tokens": 38500,
     "input_tokens": 25000,
     "output_tokens": 13500,
     "quality_score": 0.92,
     "timestamp": "2025-01-19T10:30:00Z"
   }
   ```

6. **Output Examples:**
   - Text format: Colored status indicators, clear recommendations, checkpoint reminder
   - JSON format: Structured data for automation/integration

7. **Integration Points:**
   - Document how to collect metrics (manual tracking, log parsing, future automation)
   - Reference token tracking in `codeframe/providers/anthropic.py`
   - Note dependency on Issue #3 for quality score calculation
   - Suggest future integration with `.claude/commands/` for automated checks

8. **Error Handling:**
   - Graceful handling of missing/invalid input files
   - Clear error messages for validation failures
   - Exit codes: 0=OK, 1=WARNING, 2=CRITICAL, 3=ERROR

**Style:** Follow project conventions from `pyproject.toml` (Black formatting, type hints, 100 char line length). Include comprehensive docstrings and inline comments. Add shebang for direct execution.

### CLAUDE.md(MODIFY)

Update the development guidelines to reference the new context management system.

**Changes to make:**

1. **Add new section after "Recent Changes" (around line 55):**
   ```markdown
   ## Context Management for AI Conversations
   
   To maintain quality in long AI conversations, follow the context management rules:
   - **Token Budget**: ~50k tokens per conversation (see `.claude/rules.md`)
   - **Checkpoints**: Every 5 AI responses, run tests and ask "continue or reset?"
   - **Quality Monitoring**: Use `scripts/quality-ratchet.py` to detect degradation
   - **Context Handoff**: Use template in `.claude/rules.md` when starting new conversations
   
   See [.claude/rules.md](.claude/rules.md) for complete guidelines.
   ```

2. **Update "Commands" section (around line 37-43):**
   Add reference to quality monitoring:
   ```markdown
   # Quality monitoring
   python scripts/quality-ratchet.py --input metrics.json  # Check conversation health
   ```

3. **Add to "Documentation Navigation" section (around line 6-13):**
   Add `.claude/rules.md` to the quick reference list:
   ```markdown
   - **Context management**: [.claude/rules.md](.claude/rules.md) (AI conversation quality)
   ```

**Rationale:** CLAUDE.md is the primary AI assistant development guidelines document (line 1-2), so it should reference the new context management workflow. The changes are minimal and non-disruptive, following the existing structure and style.

### scripts/quality-ratchet-example.json(NEW)

Create an example metrics input file for the quality-ratchet.py script to demonstrate usage.

**Content:**
```json
{
  "response_count": 12,
  "total_tokens": 38500,
  "input_tokens": 25000,
  "output_tokens": 13500,
  "quality_score": 0.92,
  "timestamp": "2025-01-19T10:30:00Z",
  "conversation_id": "example-conversation",
  "notes": "Example metrics file for quality-ratchet.py. Replace with actual conversation metrics."
}
```

**Purpose:**
- Provide a concrete example for users
- Document the expected input format
- Enable quick testing of the quality-ratchet.py script
- Serve as a template for manual metric tracking

**Usage Documentation:**
Include a comment block at the top explaining:
- How to collect these metrics manually
- How to run the script with this file
- What each field represents
- Future automation possibilities

### README.md(MODIFY)

Add a brief mention of the context management system in the documentation section.

**Change location:** In the "Documentation" section (around line 659-698), add a new subsection under "Project-Wide Documentation":

```markdown
#### AI Development Workflow
- **[.claude/rules.md](.claude/rules.md)** - Context management for AI conversations
- **[scripts/quality-ratchet.py](scripts/quality-ratchet.py)** - Conversation quality monitoring
```

**Rationale:** The README.md already has a comprehensive documentation section (lines 659-698) that lists all major documentation files. Adding the new context management files here ensures discoverability. The placement under "Project-Wide Documentation" is appropriate since this is a meta-level development process, not a feature of the CodeFRAME system itself.

**Style:** Follow the existing format with bold file paths and brief descriptions, consistent with other entries in the documentation section.

---

Developer Humor

🔄 Context Management: Because even AI needs a fresh start!\n>\n> *\Have you tried turning it off and on again?*\n> — IT wisdom, now for conversations\n>\n> 📊 Token budget: 50k\n> 🎯 Checkpoint: Every 5 responses \n> 🔁 Reset: Before quality drops\n> 📝 Handoff: Copy, paste, continue!\n>\n> Keep calm and reset context. 🧘‍♂️

---

Execution Information

Branch: main
Commit: d0e2480

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[frankbria]

Resolved in PR #20 - Context Management System complete. Comprehensive guidelines documented in .claude/rules.md (token budget, checkpoint system, auto-reset triggers, context handoff template). Auto-suggestion integrated with quality-ratchet.py. CLAUDE.md updated with context management section. Example JSON created for testing.