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