<fd> is this project's FlowDeck directory, the one fd-state path prints (~/.fd-plan/<project>/, or <project>/.fd-plan/ when the storage setting is project).

Context Budget Skill

Treat context window as a finite resource. Every token loaded — files, rules, tool outputs, conversation history — consumes budget. Optimizing context improves speed, cuts costs, and prevents mid-session truncation.

When to Activate

Activate when:

• A session exceeds 50K tokens or feels sluggish
• You are about to load large files, MCP tools, or heavy rulesets
• You want to audit and slim down your FlowDeck setup
• You are designing new skills, agents, or workflows

Core Principles

• Load less, get more — context quality beats context quantity
• Measure before optimizing — know your current burn rate
• Batch over chat — accumulate work, run checks once
• Right-size the model — light tasks do not need the strongest model

Why Context Budget Matters

Hard Limits (Examples)

Treat 80% of the window as your practical maximum. Beyond that, truncation risk rises sharply.

Skill Size Audit

Oversized skills waste context on every activation. Audit yours regularly.

Thresholds

How to Audit

# Count lines in all skills
find src/skills -name "SKILL.md" -exec wc -l {} + | sort -n

# Flag skills over 300 lines
find src/skills -name "SKILL.md" -exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 300 ] && echo "$lines $1"' _ {} \;

# Check description word counts
grep -r "^description:" src/skills/ | awk '{print NF, $0}' | sort -n

Remediation

• Split oversized skills — extract sub-topics into separate skills
• Shorten descriptions — under 25 words is ideal; under 30 is required
• Use stage-gated rules — load heavy rules only in execute or verify stages
• Defer heavy context — load <fd>/architecture.md only when needed

Model Routing Strategy

Not every task needs the strongest model. Route by complexity.

Routing by cost

• cheap: structural lookups, listings and summaries go to the read-only Explore subagent (or a forked skill with model: haiku, like fd-map)
• standard: implementation and test work stays in the main conversation
• expensive: design decisions, debugging and security review run on the strongest model

Do not escalate a cheap task to an expensive model.

Prefer CLI Tools Over MCPs

MCP servers add context overhead: schema discovery, tool definitions, and response envelopes. Native CLI tools are leaner.

When MCPs Are Worth It

• Complex multi-step operations (e.g., create PR + add reviewers + set labels)
• Operations requiring authentication tokens you do not have locally
• Structured data return that CLI would require parsing

Accumulator + Batch Pattern

Chatty sessions burn context fast. Accumulate edits, then run checks once.

Anti-Pattern: Chatty Loop

Edit file A → run test → fix error → edit file B → run test → fix error → edit file C → run test

Each test run consumes output tokens. Three runs = 3x test output in context.

Preferred: Batch + Single Check

Edit file A
Edit file B
Edit file C
Run tests once
Fix all errors

In FlowDeck

Use /flowdeck:fd-checkpoint after a batch of edits, then /flowdeck:fd-resume to continue. This preserves your work without carrying full error output forward indefinitely.

Strategic Context Clearing

Long sessions accumulate noise: failed attempts, dead-ends, large tool outputs. Clear context before it degrades quality.

When to Checkpoint

Resume Pattern

1. `/flowdeck:fd-checkpoint` — save current state to STATE.md
2. Start fresh session
3. `/flowdeck:fd-resume` — load checkpoint.json, STATE.md, plan.md, active context
4. Continue with clean context

This is cheaper than carrying 80K tokens of conversation history.

Rule Loading Optimization

FlowDeck uses stage-gated rules. Only rules matching the current stage are loaded.

Keep Rules Focused

• One concern per rule file
• Use stages array to gate loading
• Set always_on: false for heavy rules
• Keep rules under 150 lines when possible

Audit with:

# Find rules loaded in every stage (always_on = true)
grep -r "always_on: true" src/rules/

# Find oversized rules
find src/rules -name "*.md" -exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 200 ] && echo "$lines $1"' _ {} \;

Code Modularity Benefits

Smaller files = less context per task. A 400-line file forces the model to hold the entire file in working memory. Four 100-line files let the model focus on one at a time.

Splitting Guidance

• One responsibility per file
• Extract utilities to utils/ or helpers/
• Extract types to types.ts
• Use the blast-radius procedure in fd-codenav to find natural split points — it reveals which dependents are independent

Self-Audit Checklist

Run this monthly or when context feels heavy:

Skills

• No SKILL.md exceeds 400 lines
• No skill description exceeds 30 words
• Unused skills removed from .claude/skills/

Rules

• No rule file exceeds 200 lines
• Heavy rules are stage-gated (always_on: false)
• No redundant rules (same topic, different files)

Workflows

• Tasks are batched before verification runs
• /flowdeck:fd-checkpoint used at natural boundaries
• Model routing respects task complexity

Codebase

• No source file exceeds 800 lines
• Core modules are under 400 lines
• Large files have clear split candidates via the fd-codenav blast-radius procedure

Session Hygiene

• MCP tools used only when CLI is insufficient
• Large outputs (logs, diffs) are summarized, not pasted raw
• Failed attempts are checkpointed, not retried endlessly

Quick Wins

1. Truncate diffs — git diff | head -50 instead of full diff
2. Summarize logs — tail -20 instead of full log file
3. Use LSP document symbols — find symbols without reading entire files
4. Load rules on demand — load-rules instead of pre-loading everything
5. Split before you grow — when a file hits 400 lines, plan the split

Related Skills

• plan-task — break work into right-sized chunks
• performance-profiling — measure before optimizing
• context-load — load only the context you need

References

• /flowdeck:fd-checkpoint — save session state, clear context
• /flowdeck:fd-resume — restore from checkpoint
• load-rules — stage-gated rule loading
• LSP document symbols — symbol search without full-file reads
• the fd-codenav blast-radius procedure — find split points in large files
• LSP references and call hierarchy — a symbol's callers and callees