auto-context

# Auto-Context — Situational Awareness Protocol (Meta-Skill) Before you act, understand where you are. This skill ensures the AI loads critical project context automatically before any major action, preventing wasted effort, duplicate work, and misaligned implementations. ## Installation ### OpenClaw / Moltbot / Clawbot ```bash npx clawhub@latest install auto-context ``` --- ## When to Activate This skill triggers automatically based on the current action. Do not wait for the user to ask — proactively load context when any of these conditions are met. | Trigger | Why | Minimum Context | |---------|-----|-----------------| | Starting a new task | Understand priorities, avoid conflicts | Critical + High | | Implementing a feature | Know the plan, constraints, recent changes | Critical + High | | Refactoring code | Understand what changed recently, what's planned | Critical + High + Medium | | Debugging an issue | Check recent changes, known issues, discoveries | Critical + High + Medium | | Planning or scoping work | Full picture of roadmap, backlog, progress | All levels | | Session start or resume | Rebuild mental model from last session state | Critical + High | | Before a handoff | Ensure nothing is missed in transition | All levels | --- ## Context Files to Read Read these files in priority order. Stop early if the task is narrow and lower-priority files are clearly irrelevant. | Priority | File | Purpose | Read When | |----------|------|---------|-----------| | Critical | `TODO.md` | Current tasks, backlog, and priorities | Always | | Critical | `roadmap.md` | Phase status, milestones, project direction | Always | | High | `task_plan.md` | Active task breakdown and implementation plan | File exists | | High | `.cursor/handoffs/*.md` | Recent handoff notes (read last 3 by date) | File exists | | Medium | `findings.md` | Research results, discoveries, decisions made | Relevant to task | | Medium | `CHANGELOG.md` | Recent changes and their rationale | Relevant to task | | Low | `.cursor/sessions/*.md` | Session summaries (read last 2 by date) | Planning or debugging | ### Alternate Locations Some projects use different paths. Check these fallbacks if primary paths are empty: | Primary | Fallback | |---------|----------| | `TODO.md` | `docs/TODO.md`, `ai/TODO.md` | | `roadmap.md` | `docs/roadmap.md`, `ROADMAP.md` | | `task_plan.md` | `docs/task_plan.md`, `.cursor/task_plan.md` | | `findings.md` | `docs/findings.md`, `.cursor/findings.md` | --- ## Context Loading Strategy ### Step 1: Load Critical Files (Always) ``` Read TODO.md → Extract: current task, next priorities, blockers Read roadmap.md → Extract: current phase, active milestone, upcoming deadlines ``` If either critical file is missing, warn the user: > "No TODO.md found. Consider creating one to track tasks." ### Step 2: Load High-Priority Files (If They Exist) ``` Read task_plan.md → Extract: implementation steps, acceptance criteria Glob .cursor/handoffs/*.md → Read last 3 by modification date ``` ### Step 3: Load Medium/Low Files (If Relevant) Only read these when the current task benefits from historical context: - **Debugging?** — Read `findings.md` and `CHANGELOG.md` - **Planning?** — Read everything including session files - **Quick fix?** — Skip medium and low entirely ### Step 4: Synthesize and Present After loading, produce a context summary (see format below) before proceeding with the task. --- ## Staleness Detection Check modification dates on all loaded files. Flag files that may contain outdated information. | Age | Status | Action | |-----|--------|--------| | < 24 hours | Fresh | Use as-is | | 1-7 days | Current | Use as-is, note the age | | 7-30 days | Stale | Warn: "{file} last updated {N} days ago — verify before relying on it" | | > 30 days | Outdated | Warn: "{file} is {N} days old and may no longer reflect project state" | To check file ages on macOS: ```bash stat -f "%m %N" TODO.md roadmap.md task_plan.md findings.md CHANGELOG.md 2>/dev/null ``` On Linux: ```bash stat -c "%Y %n" TODO.md roadmap.md task_plan.md findings.md CHANGELOG.md 2>/dev/null ``` --- ## Context Summary Format After loading context, present a concise summary using this template. Keep it tight — the goal is awareness, not repetition. ```markdown ## Context Loaded **Current Phase:** {phase from roadmap} **Active Milestone:** {milestone and progress} **Current Task:** {from TODO.md or task_plan.md} - Status: {in-progress / blocked / not started} - Blockers: {any blockers, or "none"} **Recent Changes:** - {last 2-3 items from CHANGELOG or handoffs} **Relevant Findings:** - {key discoveries that affect the current task, or "none"} **Stale Warnings:** - {any staleness warnings, or "all context is fresh"} ``` If no context files exist at all, output: ```markdown ## Context Loaded No project context files found. Operating without historical context. Consider creating TODO.md and roadmap.md to enable context-aware assistance. ``` --- ## Integration Points This skill connects to other workflow commands and should run as a precursor. | Command | How Auto-Context Integrates | |---------|-----------------------------| | `/start-task` | Loads full context before beginning work; populates task plan | | `/intent` | Reads roadmap and TODO to validate intent against project direction | | `/workflow` | Provides the "understand" phase of any workflow automatically | | `/progress` | Uses TODO.md and task_plan.md to assess completion status | | `/handoff-and-resume` | Reads last handoff to rebuild state on resume | | `/session-summary` | Cross-references loaded context with session actions for accuracy | ### Execution Order ``` User triggers action → Auto-Context activates (this skill) → Context summary presented → Primary skill/command executes with full awareness ``` --- ## Quick Reference ``` Context Loading Checklist: 1. Read TODO.md (critical) 2. Read roadmap.md (critical) 3. Read task_plan.md (if exists) 4. Read last 3 handoffs (if exist) 5. Check file staleness 6. Read findings/changelog (if relevant) 7. Present context summary 8. Proceed with task ``` --- ## NEVER Do 1. **NEVER skip critical files to save time** — leads to duplicate work and conflicting implementations 2. **NEVER load every file regardless of task** — wastes tokens and dilutes focus with irrelevant info 3. **NEVER ignore staleness warnings** — stale context causes decisions based on outdated assumptions 4. **NEVER read files without summarizing** — raw file dumps overwhelm; always synthesize first 5. **NEVER assume context from memory alone** — sessions are stateless; always re-read files 6. **NEVER silently proceed when no context exists** — user should know they're operating blind 7. **NEVER read handoffs/sessions beyond the limit** — last 3 handoffs and last 2 sessions are sufficient