Small Context Coding

Use this skill to keep coding work effective when the model context is limited.

Core operating mode

Treat the model as a short-working-memory engineer.

Do not try to keep the whole project in chat context.

Store project state in files and retrieve only what is needed for the current step.

Default workflow

1. Classify the task size.
2. Create or update a task plan file before broad changes.
3. Read only the minimum files needed to decide the next step.
4. Split the work into small closed loops: inspect -> change -> verify.
5. Use sub-agents only to isolate distinct subproblems.
6. Write checkpoints after each meaningful phase.

Task size heuristic

Small

• One file or one obvious fix
• No sub-agent
• No extra planning file unless requested

Medium

• A few files or one subsystem
• Make a short plan
• Consider one sub-agent for investigation only

Large

• Multiple modules, unclear root cause, or feature work across boundaries
• Create plan + todo + checkpoint files
• Delegate investigation or isolated implementation to sub-agents
• Keep main session focused on orchestration and decisions

Required file-based state

For medium or large tasks, create these under a working notes folder such as notes//:

• plan.md — goal, constraints, phases
• todo.md — actionable checklist
• checkpoint.md — current state, decisions, next step

Keep each file short and current.

Do not duplicate long chat history into these files.

Planning rules

A plan should contain:

• task goal
• current understanding
• files/modules likely involved
• ordered steps
• verification method

If the task changes materially, update the plan before continuing broad edits.

Context discipline rules

• Never read whole directories into context without a reason.
• Prefer targeted reads and searches.
• Summarize findings into notes instead of carrying raw outputs forward.
• After a phase is complete, compress it into a checkpoint and move on.
• Do not mix unrelated problem threads in one run when avoidable.

Sub-agent rules

Use a sub-agent when one of these is true:

• investigation can be isolated from implementation
• one subsystem can be analyzed independently
• you need a clean context for an experiment
• the main session is becoming an overloaded coordinator

Do not use sub-agents for trivial single-file edits.

Do not spawn many sub-agents unless there are clearly separate workstreams.

Good sub-agent tasks

• trace a call chain for one feature
• inspect one module and summarize risks
• draft a patch for one bounded component
• write or repair one test area

Generate brief files with:

python3 /home/nick/.openclaw/workspace/skills/small-context-coding/scripts/generate_subagent_brief.py "<task-name>" "<scope>" "<verification>" <repo-root>

Read references/subagent-patterns.md for prompt shapes and references/usage-guide.md for a concrete example.

Main session responsibilities

• define task boundaries
• decide delegation
• merge findings
• choose final implementation direction
• verify final result

Verification rules

After each implementation step, run the smallest meaningful check:

• targeted test
• lint/typecheck for changed area
• build of affected package
• direct inspection if no automated check exists

Read references/verification-defaults.md for stack-specific defaults before choosing a verification command.

Never claim completion without a verification step or explicit blocker.

A task is only done when these are true:

• the requested change is implemented or explicitly blocked
• the notes reflect the current state
• one meaningful verification step has run, or the blocker is named clearly
• the next follow-up is obvious from checkpoint.md if more work remains

Recommended note templates

If notes do not exist, create them from the bundled templates in references/templates.md.

For a real task, prefer initializing them with scripts/init_task.py.

Read references/usage-guide.md when you want a concrete flow for medium or large tasks.

Read references/verification-defaults.md when selecting the smallest useful validation command for a stack.

Anti-patterns

Avoid:

• giant upfront context dumps
• broad refactors without a written plan
• keeping important state only in chat
• asking one session to investigate, design, implement, and validate many unrelated things at once
• using sub-agents just because they exist

Initialization

To set up a task workspace for medium or large work, run:

python3 /home/nick/.openclaw/workspace/skills/small-context-coding/scripts/init_task.py "<task-name>" <repo-root>

This creates notes//plan.md, todo.md, and checkpoint.md if they do not already exist.

To verify the helper workflow end to end, run:

python3 /home/nick/.openclaw/workspace/skills/small-context-coding/scripts/smoke_test.py

Iteration guidance

Keep the skill lean.

Improve it after real use by refining:

• task size thresholds
• sub-agent delegation patterns
• note templates
• verification defaults per language or framework