CHENG-LIANG1/badass-skills

Context Architect

Preserve decision quality as context grows. Treat context as an index to trusted state, not as an archive of the conversation.

Build the working set

Maintain five distinct blocks. Keep each one compact and update it when reality changes.

1. Mission

   • Objective and observable definition of done
   • User authorization boundary and explicit exclusions
   • Invariants that must survive every handoff

2. Evidence map

   • Record each decision-relevant fact as: claim, source pointer, observation time, and freshness risk.
   • Prefer files, commands, tests, API results, and current UI state over earlier summaries.
   • Separate observation from inference. Mark unverified memory or screen history as potentially stale.

3. Decision ledger

   • Preserve decisions that constrain later work: choice, rationale, rejected alternatives, consequences, and invalidation trigger.
   • Summarize the decision rather than copying dialogue. Do not turn a temporary workaround into a permanent rule.

4. Open loops

   • Track unresolved questions, failed checks, blockers, risky assumptions, and promised follow-ups.
   • Give every open loop a next probe or a condition that would close it.

5. Execution cursor

   • State the last verified action, current artifact or system state, exact next safe action, and relevant rollback point.
   • Use concrete paths, identifiers, revisions, or commands when they prevent rediscovery. Never include secrets.

Pack context by temperature

• Hot: objective, authority boundary, current state, active evidence, and next action. Keep these directly visible.
• Warm: decisions and facts likely to affect the next few steps. Compress them to one useful sentence plus a source pointer.
• Cold: completed exploration, superseded hypotheses, and background material. Retain only a labeled path or link unless it proves a disputed claim.

Promote an item when it becomes decision-relevant. Demote or remove it when it no longer changes the next action. Repetition is not importance.

Refresh at state boundaries

Refresh the working set after a user changes scope, after a material mutation, before a risky action, before handoff or compaction, and whenever a source may have drifted.

• Re-verify cheap, time-sensitive facts instead of copying them forward.
• Mark replaced decisions as superseded so an old constraint cannot silently return.
• Record failed experiments only when they rule out a credible path or change the next decision.
• Keep answer-only and review-only tasks read-only. Do not create or commit a context file unless the task authorizes project documentation or the user asks for one.

Produce a handoff packet

When another agent, session, or future run must continue the work, deliver:

Mission:
Done means:
Authority and exclusions:
Current verified state:
Evidence pointers:
Decisions and rationale:
Open loops and risks:
Exact next action:
Recheck before acting:

Write it so the next worker can act without replaying the transcript, while still knowing where to verify every consequential claim.

Run the recovery test

Before declaring the context ready, confirm a fresh worker can answer all five questions from the packet:

1. What outcome is required?
2. What changes are authorized or forbidden?
3. What is verified now, and where is the evidence?
4. What remains unresolved, and what is the next safe action?
5. Which facts or decisions could become stale?

If any answer requires guessing or rereading the full conversation, tighten the working set before handoff.