You start a session. The model re-reads your codebase, re-derives what you figured out three hours ago, and explains it back to you. You patch the third bug from a partial fix instead of fixing the cause. You tell it “do X” and it asks permission for sub-step X.1 before doing it.
This methodology is the contract that prevents that. Seven behaviors. Each one counters a specific failure mode in AI-assisted development. The reference implementation lives in CLIO; everything below cites the actual code.
The method generalizes. CLIO is one harness. Any AI coding tool with structured tool calls, persistent storage, and a checkpoint mechanism can implement it. Adapt the implementation; keep the behaviors.
Five patterns show up across every AI-assisted project that collapses under its own weight. Naming them is the first defense.
The Fresh Start Problem. Every session opens with amnesia. The model re-reads files, re-derives conclusions, re-explains what it explained yesterday. You context-switch away while it does this. Half the wall clock is rebuilding state, not making progress.
The Partial Solution Trap. The model delivers code that handles the obvious case. Edge cases crash. You report a bug, get a patch, find the next bug. The original “done” was never done.
The Symptom Patch Pattern. Errors get wrapped in try/catch instead of fixed. Broken UI gets hidden behind a loading spinner. The surface looks fixed. The underlying failure compounds.
The Scope Escape. “This is a separate problem” is the model’s favorite exit. The related bug stays unfixed. The architecture drifts toward inconsistency. You have to argue for every related improvement.
The Assumption Cascade. The model writes the fix before reading the source. The first assumption is wrong. The patches built on top of the wrong assumption make the situation worse. You spend the session correcting basic premises.
AI sessions are ephemeral. You engineer continuity, or it does not exist.
interact tool: free to call, blocking until you answer, mandatory at every checkpoint.memory_operations for LTM (entries in .clio/ltm.json with trust tiers) and session memory (key-value in .clio/memory/).A session with the right context is as effective as one with full history. The Fresh Start Problem loses most of its force here.
The model finds a bug in its working area. It fixes the bug. Not later. Not in a different session. Now.
| Situation | Action |
|---|---|
| Bug in the same system, same working area | Fix it. No asking. |
| Related issue in the same system, quick fix | Fix it. |
| Different system entirely | Report it. Ask for priority. |
| New feature outside the stated goal | Flag it. Confirm before building. |
| Architectural change | Flag it. Confirm before building. |
The rule is consistent: bugs and blockers are owned. Other systems are reported. Architecture and new features are confirmed.
Read the code. Read the docs. Trace the actual behavior. Then change something.
CLIO’s source-of-truth pattern: read HelpView.swift before documenting any keyboard shortcut. Read ConversationEngine before describing YaRN profiles. If you cannot point to the file the fact came from, the fact is an assumption.
Stop investigating when: you understand the problem, understand the impact, and have an action plan. If investigation is running longer than implementation would, start building and use iteration to verify assumptions.
Fix the cause, not the symptom. Verify the fix prevents recurrence under similar conditions. If it does not, you have not found the root.
Five Whys is enough tooling for most cases. Ask why. Ask why the answer is true. Ask again. By the fifth iteration, the cause usually surfaces.
The CLIO codebase keeps a running list of root-cause fixes in .clio/ltm.json under the solution entry type. Each one stores the problem (verbatim error or observable behavior), the solution (what changed), and the verified outcome (what proves the fix worked). Symptom patches get re-opened; root-cause fixes get trusted.
No TODO placeholders. No “we will add this later.” No draft sections committed as final. If the work is started, it is finished.
The check before you commit: would you sign off on this as “done” if you were reviewing someone else’s pull request?
When a session ends, the next session must start cold and resume effectively. Handoffs are structured, not improvised.
Minimum content: - What was accomplished - What remains - Key decisions and their rationale - Discoveries worth carrying forward - Known issues to avoid
CLIO’s directory convention for handoffs is ai-assisted/YYYYMMDD/HHMM/ with a CONTINUATION_PROMPT.md, an AGENT_PLAN.md, and an optional NOTES.md. The test is the same as the one above: can the next session reach the same conclusions from only the handoff?
Document every mistake so the next session does not repeat it. Document every successful pattern so the next session can apply it. The discipline is what matters. A failure that is not recorded will recur. A pattern that is not recorded will be re-derived from scratch.
CLIO’s LTM supports this directly: add_solution for problems with verified fixes, add_pattern for working approaches with confidence levels, add_discovery for facts about the codebase. Each entry tracks its trust tier.
Trust discipline. A single-source claim is [UNVERIFIED]. To promote it, call add_corroboration with search_text plus source_agent and source_session identifying the independent observer. When an LTM entry reaches >= 2 corroborations from distinct agent:session pairs, it auto-promotes to [TRUSTED].
Patterns that violate the method. Each one feels reasonable in the moment. Each one creates problems.
The model writes code immediately after a brief file read. It assumes the surrounding code does what its name suggests. It usually does not. The fix built on that assumption makes the next bug worse. Read the call sites. Trace the data flow. Confirm before changing.
try { ... } catch (error) { console.error(error); } around the failing call. The error still happens. It just becomes invisible. The pattern recurs across the codebase because nothing indicates it is broken. Fix the cause. If the error is truly unrecoverable, surface it with actionable context so the user can act.
A feature built for the happy path. Edge cases noted in the implementation but not handled. Every partial implementation becomes a future bug report. Finish the implementation, or remove the feature. No half-built features in the codebase.
The model asks permission for every step after direction is already clear. This burns your attention on low-stakes decisions and prevents you from seeing the actual decisions that need review. Pause for direction at decision points. Execute autonomously within approved scope. Report what was done.
“Great work on X, but there are some issues with Y…” The compliment dilutes the actual problem and reads as performative. State the issue directly. Acknowledge good work specifically when it is earned, then move on.
Documentation or code committed with // TODO: explain this properly and an open issue that never closes. TODOs are technical debt that compounds. Complete the section or remove it. If something genuinely needs future work, create a tracked issue with a clear owner and link it.
“I will create the file now” instead of creating the file. Description is not action. You are waiting for results, not narration. If a tool exists for the action, use it. Tool failures provide information: read the error, adjust the approach, try again. Iterate until the tool succeeds or the failure is clearly unrecoverable.
The behaviors describe what to do. To do them you need a harness that supports them. This section shows how each behavior maps to a real implementation. The CLIO references are one path; the general guidance covers other common harnesses.
The model needs a way to pause and request input before proceeding with significant decisions.
CLIO: interact is a JSON tool call with operation: "request_input". It is free (does not consume AI Credits), synchronous (workflow continues in the same API call), and blocking (pauses until response). Use it for all collaboration rather than sending summary responses, which cost a full API turn. Format: {"name":"interact","parameters":{"operation":"request_input","message":"..."}}.
| Harness | Checkpoint mechanism |
|---|---|
| Claude Code | AskUserQuestion tool, or directional pauses |
| Cursor | Inline chat prompts, chat-UI decisions |
| Aider | /ask command for mid-session questions |
| Cline / Continue | Inline prompts at decision points |
| Custom harness | Any tool that surfaces a message and waits for input |
Required checkpoints: - Session start: multi-step work begins, plan presented - After investigation: before any code or config changes - After implementation: before committing - Status update: at significant milestones
Reading files, running tests, and following approved plans do not require a checkpoint.
The model needs an explicit operational contract. Without one, it defaults to generic helpfulness, which violates most pillars.
CLIO: .clio/instructions.md contains core identity, authority framework, tool-first operation, licensing, smart inference, completion criteria, ownership model, multi-step task management, tool call discipline, user collaboration, response quality, and response formatting.
| Harness | Instructions file |
|---|---|
| Claude Code | CLAUDE.md at project root |
| Cursor | .cursorrules |
| Aider | CONVENTIONS.md referenced via --read |
| Cline | .clinerules |
| Custom harness | Any persistent file loaded on session start |
Sections to include: - Identity and role - Authority and checkpoints - Tooling and tool call discipline - Output standards (formatting, language, tone) - Memory and context persistence - Anti-patterns to avoid
The shorter the file, the more important each line. Cut the generic. Keep the specific.
In-session checkpoints solve real-time direction. Cross-session memory solves the Fresh Start Problem.
CLIO: memory_operations with structured LTM types: - add_discovery: factual findings about the codebase - add_solution: error, solution, verified outcome - add_pattern: reusable working approach with confidence level - add_corroboration: independent verification, promotes unverified to trusted - recall_sessions: search prior session history (scored by relevance, newest first) - update_ltm: edit an existing LTM entry in place - prune_ltm: trim old or low-confidence entries - ltm_stats: report current entry counts by type
Plus session-scoped memory via store, retrieve, search, list, and delete for working context that does not need to survive sessions.
General guidance: - A notes/ directory with dated markdown files - Knowledge bases with searchable entries and metadata - Project trackers (Linear, GitHub Issues) for known bugs and decisions - Inline source comments for project-specific gotchas
The required properties are universal: entries must be searchable, must have metadata (date, source, confidence), and must distinguish verified knowledge from assumptions.
Trust discipline: single-source claims are [UNVERIFIED]. The promotion mechanism is documented in Seven Behaviors > Learning from Failure.
Mental tracking fails by the third step. Complex tasks need explicit tracking.
CLIO: todo_operations with a create-first workflow: 1. Write the full todo list (all tasks not-started) 2. Mark the current task in-progress 3. Do the work 4. Mark the todo completed immediately after finishing 5. Move to the next todo
The discipline is universal: create todos before starting, update them as you go, never batch updates. A todo list that lags reality is worse than no todo list.
Without explicit scope rules, the model either asks permission for everything or assumes authority for everything. Both fail.
CLIO’s Authority Framework grants full authority to: - Act autonomously after checkpoint approval - Fix bugs discovered during work without additional permission - Commit code solving stated problems - Modify configs, scripts, and files pursuing approved goals - Make reasonable inferences about missing details - Iterate through errors until resolution
Checkpoints are mandatory at session start, after investigation, after implementation, and at status updates. Work continues between checkpoints unless explicitly stopped.
General guidance for your instructions file, define: - Full authority: what the model can do without asking (within approved scope) - Checkpoint required: architectural decisions, new features, cross-system changes - Out of scope: different repositories, production deployments, user data modifications
The default should be: act within approved scope, report outside it.
Saying “I will create the file now” is wasted output. Calling the file-creation tool is the work.
The rule is universal: if a tool exists for the action, use it. Do not narrate what you are about to do. Just do it. Tool failures are signals: read the error, adjust, retry. Iterate until the tool succeeds or the failure is clearly unrecoverable. A tool that fails is a reason to try a different approach, not a reason to stop.
In CLIO, the tool surface (file operations, version control, terminal, memory, web, todo, code intelligence, interact, apply_patch, remote execution, skill operations) is enumerated in the agent’s system prompt at session start. The model knows what is available without re-discovering it.
Reusable prompt templates for common tasks reduce repetition and ensure consistency across sessions.
CLIO: skills are loaded via skill_operations and treated as instructions for the loaded task. The default catalog includes design, design-review, doc, explain, fix, init, init-with-prd, review, and test, plus custom skills ansi-terminal-display, bbs-terminal-display, llama-cpp-steamos, perl-best-practices, and writing-voice.
A skill earns its keep when a task recurs frequently and the prompt itself is non-trivial. A skill that gets used twice a year is overhead.
The general pillars above apply to any domain. Software work has specific pitfalls worth calling out.
Every technical claim in documentation must match the source code. Defaults, parameters, file paths, model lists - all of it. Wrong documentation is worse than no documentation because it creates false confidence.
The verification process: 1. Read the documentation claim 2. Identify the source file that contains the truth 3. Read the source file 4. Confirm the claim matches 5. If it does not match, fix the documentation
This is the source verification principle the SAM documentation follows as a project-wide rule.
Different transports have different write semantics. print() on a non-blocking Unix socket does short writes for messages over the socket buffer boundary. The receiver gets partial data, never finds the expected delimiter, and buffers forever.
The fix is documented in the CLIO LTM as a root-cause solution: when writing to a non-blocking socket, a pipe, or any streaming transport, use a blocking write loop that handles short writes. Reserve line-buffered writes for terminals and files. Match the write mechanism to the transport.
A long-running command should block until complete. Backgrounding it does not make it faster - it makes the next step run before the data is ready.
The rule: only background commands designed to run independently (servers, watchers). Sequential commands should run sequentially. If a command takes too long, find a faster way to do it, not a parallel way to wait for it.
Commented-out code rots. It stays in the file, contradicts the active code, confuses the next reader. Git remembers. The source file does not need to.
The rule: keep code active or delete it. The git history is one search away.
Every change verified before commit. The verification method depends on the project: - Compiled languages: build succeeds, tests pass - Interpreted languages: tests pass, scripts run without error - Documentation: pages render, links resolve, examples execute
A commit is a promise that the change works. Broken commits create trust debt that compounds across the project. The verification cost is always less than the recovery cost.
When reporting a blocker, provide the deep-dive technical details: what was tried, what failed, what the error said, what the next step would require. High-level summaries waste your time re-deriving what the model already knows.
The format that works:
Blocked on [X]. Tried: [list]. Need: [specific]. Options: [alternatives]. Should I continue investigating, or wait for your guidance?Specifics in, specifics out. The summary is not the blocker - the missing information is.
Before starting work: - Read the relevant code and documentation - Identify the source files that contain the answers you need - Read your project’s instructions file - Search memory for prior work on this area
During work: - Investigate before changing - Find the root cause, not the symptom - Complete the implementation, do not half-finish it - Update todos as you go - Iterate when tools fail
At decision points: - Pause and request explicit approval - Present findings, not just plans - Be specific about what you are asking permission for
When stuck: - Read the actual error, do not paraphrase it - Search memory for similar problems - Try a different approach - Report blockers with technical depth, not summaries
When ending work: - Document what was accomplished - Document what remains - Document discoveries and decisions made - Verify everything is committed and tested - Confirm handoff content is sufficient for the next session to resume cold