ADR-052: Intent-Aware Context Management
Status: Accepted Date: January 4, 2026 Updated: 2026-02-03 (Migrated to coditect-core per ADR-150) Authors: CODITECT AI Team Deciders: Hal Casteel
Context
The Reality of Human Workflow
Users frequently jump between projects within a single session. This is not ideal but is the reality of how humans work:
- Mid-session project switches ("now let's work on pricing research")
- Interleaved tasks across multiple codebases
- Context switches triggered by urgent issues
- Return to previous work after interruptions
The Problem
Without intent-aware context management:
- Lost Context: System continues with wrong plan/tasklist
- Orphaned Tasks: Work done without tracking
- Plan Proliferation: New plans created when existing ones should be used
- Assumption Errors: System assumes context instead of asking
Requirements
- Detect when user changes context (different project, different plan)
- Search for existing plans that match the new context
- Ask for clarification when unclear (NEVER assume)
- Guard against proliferation of plans and tasklists
Decision
Implement an Intent-Aware Context Management System with four core components:
1. Context Switch Detector
Detects signals that indicate a context change:
┌──────────────────────────────────────────────────────────────┐
│ CONTEXT SWITCH SIGNALS │
├──────────────────────────────────────────────────────────────┤
│ │
│ EXPLICIT SIGNALS (High Confidence): │
│ • "now let's work on..." │
│ • "switch to the X project" │
│ • "back to the Y module" │
│ • "different project/task/feature" │
│ │
│ IMPLICIT SIGNALS (Medium Confidence): │
│ • References files outside current project │
│ • Mentions submodule not in current context │
│ • Request doesn't match ANY task in current plan │
│ • Different directory/repository mentioned │
│ │
│ LOW CONFIDENCE (Requires Confirmation): │
│ • Ambiguous project references │
│ • Generic task descriptions │
│ • No clear project indicator │
│ │
└──────────────────────────────────────────────────────────────┘
2. Plan Search System
When context switch detected, search for matching plans:
# Search priority order
1. Exact project name match in plan filename
2. Task description similarity (fuzzy match)
3. Submodule path correlation
4. Keywords in existing task descriptions
5. Recent activity in task_tracking table
3. Clarification Protocol
CRITICAL RULE: When unclear, STOP and ASK. Never assume.
┌──────────────────────────────────────────────────────────────┐
│ CLARIFICATION DECISION TREE │
├──────────────────────────────────────────────────────────────┤
│ │
│ Context Switch Detected │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Search Plans │ │
│ └───────┬───────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ │ │
│ FOUND NOT FOUND │
│ │ │ │
│ ▼ ▼ │
│ ┌─────┐ ┌─────────────────────────────────┐ │
│ │ 1 │ │ "I don't see a plan for [X]. │ │
│ │match│ │ Should I: │ │
│ └──┬──┘ │ a) Add to current plan? │ │
│ │ │ b) Create new plan for [X]? │ │
│ │ │ c) Search for existing plan?" │ │
│ │ └─────────────────────────────────┘ │
│ │ │
│ ┌──┴──┐ │
│ │ >1 │ │
│ │match│ │
│ └──┬──┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ "Found multiple matching plans: │ │
│ │ - PLAN-A.md │ │
│ │ - PLAN-B.md │ │
│ │ Which should we use?" │ │
│ └─────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
4. Proliferation Guard
Prevents unnecessary creation of new plans:
┌──────────────────────────────────────────────────────────────┐
│ PROLIFERATION GUARD RULES │
├──────────────────────────────────────────────────────────────┤
│ │
│ BEFORE creating ANY new plan: │
│ │
│ 1. FUZZY SEARCH existing plans │
│ • Check for similar names (Levenshtein distance < 3) │
│ • Check for keyword overlap > 50% │
│ • Check for same submodule/project references │
│ │
│ 2. COUNT plans in category │
│ • If 3+ similar plans exist: WARN user │
│ • Suggest consolidation before creating new │
│ │
│ 3. REQUIRE explicit approval │
│ • Never auto-create plans │
│ • User must confirm: "Yes, create new plan for X" │
│ │
│ 4. SUGGEST alternatives │
│ • "Add tasks to existing PILOT-PLAN.md?" │
│ • "Merge with similar PRICING-RESEARCH.md?" │
│ • "Create sub-section in project-plan.md?" │
│ │
└──────────────────────────────────────────────────────────────┘
Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ INTENT-AWARE CONTEXT MANAGEMENT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ USER INPUT │
│ "now let's work on the pricing research" │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ CONTEXT SWITCH DETECTOR │ │
│ │ │ │
│ │ Patterns: │ │
│ │ • "now let's", "switch to", "different project" │ │
│ │ • References files outside current project │ │
│ │ • Request doesn't match ANY task in current plan │ │
│ │ • Different submodule/directory mentioned │ │
│ └────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ PLAN SEARCH │ │
│ │ │ │
│ │ Search for existing plans matching: │ │
│ │ 1. Project name ("pricing-research") │ │
│ │ 2. Task description similarity │ │
│ │ 3. Submodule path │ │
│ │ 4. Keywords in existing tasks (task_tracking table) │ │
│ └────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ┌─────────────┴─────────────┐ │
│ │ │ │
│ FOUND NOT FOUND │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ "Found existing │ │ STOP AND ASK │ │
│ │ plan: PRICING- │ │ │ │
│ │ RESEARCH.md │ │ "I don't see a │ │
│ │ Continue with │ │ plan for this. │ │
│ │ this plan?" │ │ Should I: │ │
│ └──────────────────┘ │ a) Add to PILOT?│ │
│ │ b) Create new? │ │
│ │ c) Search more?"│ │
│ └──────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ PROLIFERATION GUARD │ │
│ │ │ │
│ │ Before creating new plan: │ │
│ │ • Check if similar plan exists (fuzzy match) │ │
│ │ • Warn if 3+ plans in same category │ │
│ │ • Suggest consolidation if appropriate │ │
│ │ • Require explicit approval for new plan creation │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Implementation
Components
| Component | Location | Purpose |
|---|---|---|
| Intent Context Manager | scripts/core/intent_context_manager.py | Detect switches, search plans |
| Task Plan Sync | hooks/task-plan-sync.py | Bidirectional plan↔TodoWrite sync |
| Task Tracking Enforcer | hooks/task-tracking-enforcer.py | Enforce task ID format |
| Task Tracking Schema | scripts/migrations/add-task-tracking.sql | Database schema |
Database Support
ADR-118 Compliance: The
task_trackingtable resides insessions.db(Tier 3 - Regenerable).
The task_tracking table enables fast plan matching:
-- Find tasks matching new context (sessions.db - Tier 3)
SELECT task_id, task_description, status
FROM task_tracking
WHERE task_description LIKE '%pricing%'
OR task_id LIKE '%PRICING%'
ORDER BY
CASE WHEN status = 'in_progress' THEN 0
WHEN status = 'pending' THEN 1
ELSE 2 END
LIMIT 10;
Integration Points
- Session Start: Check if resuming existing plan or starting new
- User Message: Scan for context switch signals
- TodoWrite: Sync status to all plan files
- Session End: Update plan completion status
Consequences
Positive
- No Lost Work: All tasks tracked against proper plan
- Reduced Confusion: Clear which plan is active
- Controlled Growth: Plan proliferation prevented
- User Agency: Always asks, never assumes
Negative
- Additional Prompts: User may be asked for clarification
- Processing Overhead: Each message scanned for context signals
- Learning Curve: Users must understand task ID format
Mitigations
- Make clarification prompts concise
- Cache plan search results
- Provide clear examples of task ID format
Related ADRs
- ADR-046 - Continual Learning System (task tracking foundation)
- ADR-048 - Pilot Execution Workflow (plan structure)
- ADR-051 - Work Discovery System (task discovery)
- ADR-053 - Cloud Context Sync Architecture
- ADR-118 - Four-Tier Database Architecture
Enforcement Mechanisms
To ensure agents and skills actually use this framework:
1. Hook-Based Enforcement
{
"hooks": {
"PreToolUse": [
{
"matcher": "TodoWrite",
"hooks": ["python3 hooks/task-tracking-enforcer.py --level soft"]
}
],
"PostToolUse": [
{
"matcher": "TodoWrite",
"hooks": ["python3 hooks/task-plan-sync.py"]
}
]
}
}
2. CLAUDE.md Directives
Add to agent/skill prompts:
- "Always use [TASK.ID] format in TodoWrite"
- "Check for context switches before starting new work"
- "Never create new plans without explicit user approval"
3. Quality Gates
- Retrospective penalizes work done without task tracking
- Skills without task IDs score lower
- Reports highlight untracked work
Success Metrics
| Metric | Target |
|---|---|
| Context switches detected | >90% |
| Plans matched correctly | >85% |
| User clarification rate | <20% of switches |
| Plan proliferation | <10% growth/month |
| Untracked work | <5% of sessions |
Document Version: 1.0.0 Last Updated: 2026-02-03 Migrated: 2026-02-03 (ADR-150) Certainty Level: HIGH (90%)