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

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:

stat -f "%m %N" TODO.md roadmap.md task_plan.md findings.md CHANGELOG.md 2>/dev/null

On Linux:

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.

## 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:

## 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