ilandahan/AID / skills/context-tracking
context-tracking
VerifiedReal-time work context tracking for session continuity. Maintains task/step state across sessions, tracks progress, manages logs, integrates with phase enforcement.
| File | Kind | Size |
|---|---|---|
| SKILL.extended.md | markdown | 17.2 KB |
| SKILL.md | skill md | 4.0 KB |
| references/context-schema.md | markdown | 7.5 KB |
| references/session-management.md | markdown | 13.2 KB |
| references/step-templates.md | markdown | 12.1 KB |
SKILL.extended.md
View on GitHub---
name: context-tracking
description: Real-time work context tracking for seamless session continuity. Use this skill to maintain task/step state across sessions, track progress on current work, manage session logs, and integrate with phase enforcement. Essential for multi-session projects and team handoffs.
---
# Context Tracking Skill
Maintain real-time work context in `.aid/context.json` for seamless session continuity, integrated with phase enforcement and quality feedback systems.
## PRIORITY 1: Context State Management
```
┌─────────────────────────────────────────────────────────────────┐
│ CONTEXT TRACKING CORE RULE │
│ │
│ Claude MUST maintain context at ALL times: │
│ │
│ 1. READ context before starting any work │
│ 2. UPDATE context on every significant change │
│ 3. SYNC with phase state (.aid/state.json) │
│ 4. INTEGRATE with feedback system (/aid end) │
│ 5. SAVE context at conversation end │
└─────────────────────────────────────────────────────────────────┘
```
## Context Update Triggers
| Moment | Action | Updates |
|--------|--------|---------|
| Session start | Read context | Load previous/current/next |
| Starting new task | Shift tasks | Reset steps, log entry |
| Starting new step | Shift steps | Add to session log |
| Completing step | Mark done | Notes, timestamp, shift |
| Completing task | Mark done | Shift tasks, prompt feedback |
| Progress milestone | Update % | Notes, timestamp |
| Phase change | Sync state | Update phase in context |
| End of conversation | Final save | All pending changes |
## Context Structure
### `.aid/context.json`
```json
{
"last_updated": "2024-12-11T15:30:00Z",
"session_id": "2024-12-11-afternoon",
"phase": {
"current": 4,
"name": "development",
"started_at": "2024-12-10T09:00:00Z"
},
"development_tracking": {
"interaction_count": 7,
"last_quality_check": "2024-12-11T14:00:00Z",
"quality_check_threshold": 10
},
"project": {
"name": "user-authentication",
"documents": {
"prd": "docs/prd/2024-12-09-user-authentication.md",
"tech_spec": "docs/tech-spec/2024-12-10-user-authentication.md",
"implementation_plan": "docs/implementation-plan/2024-12-10-user-authentication.md"
}
},
"tasks": {
"previous": {
"key": "PROJ-123",
"title": "Create LoginForm component",
"status": "done",
"completed_at": "2024-12-11T14:00:00Z"
},
"current": {
"key": "PROJ-124",
"title": "Create AuthService",
"status": "in_progress",
"started_at": "2024-12-11T14:15:00Z",
"jira_url": "https://company.atlassian.net/browse/PROJ-124"
},
"next": {
"key": "PROJ-125",
"title": "Create SessionManager",
"status": "todo"
}
},
"current_task_steps": {
"previous": {
"name": "Write unit tests",
"status": "done",
"completed_at": "2024-12-11T15:00:00Z",
"notes": "8 tests passing, covering all auth flows"
},
"current": {
"name": "Implement service",
"status": "in_progress",
"started_at": "2024-12-11T15:00:00Z",
"progress": "60%",
"notes": "Login and logout done, token refresh next"
},
"next": {
"name": "Integration tests",
"status": "pending"
}
},
"session_log": [
{
"timestamp": "2024-12-11T14:15:00Z",
"action": "task_started",
"details": "Started PROJ-124: Create AuthService"
},
{
"timestamp": "2024-12-11T15:00:00Z",
"action": "step_completed",
"details": "Unit tests complete: 8 tests passing"
}
],
"feedback": {
"pending_for_phase": false,
"last_feedback_at": "2024-12-10T18:00:00Z",
"sessions_since_feedback": 2
}
}
```
## PRIORITY 2: Phase Integration
```
┌─────────────────────────────────────────────────────────────────┐
│ CONTEXT-PHASE SYNCHRONIZATION │
│ │
│ context.json state.json │
│ ──────────── ────────── │
│ phase.current ◄────► current_phase │
│ project.documents ◄────► documents │
│ feedback.pending ◄────► feedback_collected │
│ │
│ On phase change: sync both files │
│ On feedback: update both files │
└─────────────────────────────────────────────────────────────────┘
```
### Phase-Aware Context
| Phase | Task Types | Step Templates |
|-------|------------|----------------|
| 1 - PRD | Requirements | User stories, acceptance criteria |
| 2 - Tech Spec | Architecture | Design, API contracts, security |
| 3 - Impl Plan | Planning | Task breakdown, estimates |
| 4 - Development | Coding | TDD cycle, implementation, review |
| 5 - QA & Ship | QA | Testing, coverage, deployment |
## Standard Step Templates by Phase
### Phase 4: Component Development
```json
{
"steps": [
{ "name": "Load task context", "order": 1 },
{ "name": "Read Tech Spec section", "order": 2 },
{ "name": "Write tests (TDD)", "order": 3 },
{ "name": "Implement component", "order": 4 },
{ "name": "Run tests / fix", "order": 5 },
{ "name": "Apply styling", "order": 6 },
{ "name": "Self code review", "order": 7 },
{ "name": "Update Jira", "order": 8 },
{ "name": "Commit", "order": 9 }
]
}
```
### Phase 4: Bug Fix
```json
{
"steps": [
{ "name": "Load task context", "order": 1 },
{ "name": "Reproduce issue", "order": 2 },
{ "name": "Write failing test", "order": 3 },
{ "name": "Implement fix", "order": 4 },
{ "name": "Verify fix", "order": 5 },
{ "name": "Update Jira", "order": 6 },
{ "name": "Commit", "order": 7 }
]
}
```
### Phase 5: QA Task
```json
{
"steps": [
{ "name": "Load task context", "order": 1 },
{ "name": "Run test suite", "order": 2 },
{ "name": "Check coverage", "order": 3 },
{ "name": "Review checklist", "order": 4 },
{ "name": "Document findings", "order": 5 },
{ "name": "Fix issues", "order": 6 },
{ "name": "Final verification", "order": 7 }
]
}
```
### Phase 1-3: Research, PRD & Document Creation
```json
{
"steps": [
{ "name": "Load context", "order": 1 },
{ "name": "Research/gather info", "order": 2 },
{ "name": "Draft document", "order": 3 },
{ "name": "Review/refine", "order": 4 },
{ "name": "Save to docs folder", "order": 5 },
{ "name": "Update context", "order": 6 }
]
}
```
## Session Log Actions
| Action | When | Details |
|--------|------|---------|
| `session_started` | /good-morning or first interaction | Session ID, loaded context |
| `task_started` | Beginning new Jira task | Task key, title |
| `task_completed` | Finishing Jira task | Task key, duration |
| `step_started` | Beginning step within task | Step name |
| `step_completed` | Finishing step | Notes, duration |
| `progress_update` | Significant progress milestone | Percentage, notes |
| `blocker_noted` | Hit a blocker | Description |
| `phase_changed` | Phase transition | From/to phase |
| `feedback_collected` | /aid end completed | Rating |
| `context_saved` | Manual context save | Reason |
| `session_ended` | End of work session | Summary |
## PRIORITY 3: Feedback Integration
```
┌─────────────────────────────────────────────────────────────────┐
│ CONTEXT-FEEDBACK FLOW │
│ │
│ Task Complete? │
│ │ │
│ ▼ │
│ Update Context (task → done) │
│ │ │
│ ▼ │
│ Check: Is this phase ending? │
│ │ │
│ ├── Yes ──▶ Prompt: "/aid end for phase feedback" │
│ │ │
│ ▼ │
│ Check: Sessions since feedback >= 3? │
│ │ │
│ ├── Yes ──▶ Remind: "Consider /aid end for feedback" │
│ │ │
│ ▼ │
│ Continue to next task │
└─────────────────────────────────────────────────────────────────┘
```
### Feedback Reminders
| Condition | Reminder |
|-----------|----------|
| Phase ending | "Run /aid end before advancing to next phase" |
| 3+ sessions without feedback | "Consider /aid end to share what worked" |
| 5+ tasks completed | "Good time for /aid end checkpoint" |
## Integration with Commands
| Command | Context Action |
|---------|----------------|
| `/good-morning` | Read context, display status, prompt continuation |
| `/context` | Display current context state |
| `/context update` | Manual context update |
| `/phase` | Sync phase between context and state |
| `/aid end` | Update feedback tracking, save context |
| `/aid improve` | Reset feedback counters |
## Error Handling
### No context.json exists
```
⚠️ No .aid/context.json found
Setting up context tracking:
1. What feature are you working on?
2. What phase are you in? (Check /phase)
3. What task are you on? (Jira key or description)
[Creates context from answers]
```
### Context is stale (>24h old)
```
⚠️ Context is stale (last updated 36 hours ago)
Last state:
- Task: PROJ-124 "Create AuthService"
- Step: Implement service (60%)
Is this still accurate?
[1] Yes, continue from here
[2] No, I completed some work offline
[3] Start fresh with new task
```
### Context-State mismatch
```
⚠️ Context-State mismatch detected
Context shows: Phase 3 (Implementation Plan)
State shows: Phase 4 (Development)
Syncing to Phase 4...
[Updates context.phase]
Note: You may need to update your current task steps.
```
## File Locations
```
.aid/
├── state.json # Phase-level state (phase-enforcement)
├── context.json # Task/step-level context (THIS SKILL)
├── approvals/ # Phase approval records
└── overrides.log # Phase override log
~/.aid/
├── feedback/
│ ├── pending/ # Unprocessed feedback
│ └── processed/ # Archived feedback
└── metrics/
└── trends.json # Aggregated metrics
```
## PRIORITY 4: Development Interaction Tracking
During Phase 4 (Development), track significant interactions to trigger periodic quality checks.
### What Counts as an Interaction
```
┌─────────────────────────────────────────────────────────────────┐
│ INTERACTION COUNTER INCREMENTS WHEN: │
│ │
│ ✓ Component/function implementation completed │
│ ✓ Test file written and saved │
│ ✓ git commit executed │
│ ✓ Code review checklist completed │
│ ✓ Bug fix verified │
│ │
│ DOES NOT INCREMENT FOR: │
│ ✗ Questions and discussions │
│ ✗ File reads without changes │
│ ✗ Context lookups │
│ ✗ Planning/thinking │
└─────────────────────────────────────────────────────────────────┘
```
### Quality Check Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ DEVELOPMENT QUALITY CHECK FLOW │
│ │
│ Interaction happens │
│ │ │
│ ▼ │
│ Is Phase 4 (Development)? │
│ │ │
│ ├── No ──▶ Skip │
│ │ │
│ ▼ │
│ Increment development_tracking.interaction_count │
│ │ │
│ ▼ │
│ interaction_count >= quality_check_threshold? │
│ │ │
│ ├── No ──▶ Continue working │
│ │ │
│ ▼ │
│ Trigger Quality Check Prompt │
│ │ │
│ ▼ │
│ User rates (1-5) or skips │
│ │ │
│ ▼ │
│ If rated: Save to feedback/pending/ │
│ Reset interaction_count to 0 │
│ Update last_quality_check timestamp │
│ Continue working │
└─────────────────────────────────────────────────────────────────┘
```
### Quality Check Prompt
When threshold reached, Claude displays:
```
═══════════════════════════════════════════════════════════════════
📊 QUICK QUALITY CHECK
You've completed ~{count} significant interactions. Quick checkpoint:
How's the session going? (1-5 or 'skip')
1 = Struggling 2 = Below avg 3 = On track 4 = Good 5 = Great
Your rating (or 'skip'): ___
Brief note (optional): ___
═══════════════════════════════════════════════════════════════════
```
### Configuration
Default threshold: 10 interactions
Can be overridden in `~/.aid/config.yaml`:
```yaml
development:
quality_check_interval: 10
quality_check_enabled: true
```
## Commands Reference
| Command | Purpose |
|---------|---------|
| `/context` | Show current context |
| `/context tasks` | Show task progression only |
| `/context steps` | Show current task steps only |
| `/context log` | Show session log |
| `/context update` | Manual context update |
| `/good-morning` | Full startup routine with context |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |