---

name: external-causal-workspace description: Use when a task is complex, ambiguous, architectural, debugging-oriented, refactoring-heavy, strategic, causal, performance-sensitive, security-sensitive, multi-file, high-impact, or likely to suffer from hallucinated verification. Builds a disk-backed causal workspace before answering, planning, or modifying files; avoid for trivial edits, simple formatting, and direct factual answers. license: MIT compatibility: Agent Skills-compatible clients with filesystem read/write access. Designed for OpenCode, Codex, Claude Code, and terminal agents. metadata: version: "0.2.1" category: reasoning tags: - causal-analysis - verification - debugging - architecture - agent-workspace - falsification - claims-ledger

External Causal Workspace Skill

Purpose

This skill turns a terminal agent into a reasoning system with an external, inspectable workspace.

The agent must not behave as a simple text generator when the task is complex. It must build and manipulate a local model of the problem before producing conclusions, plans, patches, or recommendations.

The goal is to approximate, through tool use and explicit state, a temporary external world model composed of objects, relations, constraints, causalities, invariants, competing hypotheses, tests, verification evidence, decisions, and residual uncertainty.

This is not a neural latent space. It is a practical disk-backed substitute: an external cognitive workspace that can be read, updated, checked, shared, and audited.

When to Use This Skill

Use this skill for complex or high-impact tasks, especially:

• architecture analysis;
• debugging;
• root-cause analysis;
• refactoring;
• multi-file changes;
• unclear or unstable requirements;
• strategic technical decisions;
• causal analysis;
• performance-sensitive work;
• security-sensitive work;
• tasks with multiple plausible explanations;
• tasks where a wrong answer may create future technical debt;
• tasks where verification, traceability, or falsification matters.

Do not use this skill heavily for:

• trivial questions;
• tiny isolated edits;
• simple formatting;
• direct factual answers that do not depend on local project reality;
• tasks where a full workspace would add more noise than value.

If the task is simple, answer directly and briefly explain that the skill was not needed.

Target Workspace

The active workspace is the directory from which the agent is launched, or the project root explicitly identified by the user.

The causal workspace belongs to the target project, not to the skill directory.

Use:

<project-root>/.agent/current/

The skill directory contains the protocol. The project directory contains the task state.

The agent must not write task-specific reasoning state into the skill package itself.

Current Workspace Inspection

Before acting on any repository-specific or environment-specific task, inspect only as much of the current workspace as needed.

Identify when relevant:

• the project structure;
• relevant files and folders;
• available documentation;
• build, test, and validation commands;
• constraints imposed by existing architecture;
• any existing AGENTS.md, override file, local instruction file, or task-specific guidance;
• whether .agent/current/ already exists.

The agent must not assume the architecture from memory when the task depends on local project reality.

Fresh Run Semantics

At the beginning of each new task that uses this skill, reset .agent/current/ in the target project.

Rules:

• If .agent/ does not exist, create it.
• If .agent/current/ does not exist, create it.
• If .agent/current/ already exists from a previous task, delete or overwrite its previous contents before starting the new task.
• Do not delete .agent/notes/, .agent/reports/, .agent/tmp/, or .agent/archive/ unless the user explicitly asks.
• Do not preserve historical state by default.
• If the user explicitly asks to preserve history, copy the previous .agent/current/ to .agent/archive/<timestamp-or-task-name>/ before resetting it.

The purpose of .agent/current/ is to represent the current task only. It must not silently accumulate stale reasoning from previous prompts.

Workspace Ownership

For a given task, .agent/current/ must have a single writer.

Create or overwrite:

.agent/current/owner.md

owner.md must state:

• task name or short objective;
• owning agent or role, if known;
• start time if available;
• status: active, completed, partial, blocked, or abandoned;
• whether the workspace was freshly reset.

If another active owner is detected and the user did not explicitly start a new task, do not overwrite silently. Either treat the workspace as read-only or state that a new run requires resetting .agent/current/.

Required Disk-Backed Files

For every complex, ambiguous, architectural, debugging, refactoring, strategic, causal, or high-impact task, create or update at least:

.agent/current/owner.md
.agent/current/task.md
.agent/current/world.md
.agent/current/hypotheses.md
.agent/current/claims.md
.agent/current/verification.md
.agent/current/decision.md

These files are not decoration. They are the external working memory of the agent.

The agent must read and update them during the task. The final response must be consistent with .agent/current/decision.md and with the retained claim statuses in .agent/current/claims.md. Before the final response, .agent/current/owner.md must no longer be active.

Required File Roles

owner.md

Identifies the current run and prevents accidental overwrite by another task or agent.

It should include:

• current task;
• owner;
• mode: direct, delegated, exploratory, diagnostic, or implementation-support;
• status;
• reset decision.

task.md

Defines the task boundary.

It should include:

• user objective;
• interpreted objective;
• scope;
• out of scope;
• constraints;
• success criteria;
• explicit user prohibitions;
• assumptions that still require verification.

world.md

Builds the local model of the problem.

It should include:

• objects: components, files, services, actors, concepts, data structures;
• relations: dependencies, ownership, data flow, call flow, lifecycle, temporal sequence;
• constraints: technical, functional, security, architectural, performance, compatibility;
• causalities: what produces what, what breaks what, what depends on what;
• invariants: what must remain true after the intervention;
• uncertainty zones: facts not yet verified.

hypotheses.md

Prevents single-hypothesis reasoning.

It should include competing explanations or solution paths:

| Hypothesis | Supports | Contradicts | Falsification test | Status |
|---|---|---|---|---|
| H1 | ... | ... | ... | retained/rejected/suspended |
| H2 | ... | ... | ... | retained/rejected/suspended |

Hypotheses must be rejected, retained, or suspended explicitly.

claims.md

Prevents truth-regime confusion.

It should list the important assertions that materially affect the task, typed and statused:

| ID | Claim | Type | Source / Evidence | Status | Impact | Notes |
|---|---|---|---|---|---|---|
| C-001 | ... | fact / inference / hypothesis / constraint / invariant / risk / value / decision | file, command, user statement, tool result, reasoning | verified / inferred / plausible / suspended / rejected / not-checked | low / medium / high / critical | ... |

Rules:

• fact requires an evidence anchor.
• inference must name the facts it depends on.
• hypothesis must remain distinguishable from fact until falsified or retained.
• value may guide judgement but must not masquerade as empirical proof.
• decision must be supported by retained claims and must not depend silently on rejected claims.

Use only materially important claims. Do not turn the workspace into a verbose claim dump.

verification.md

Prevents false verification.

It should include:

• commands actually run;
• files actually inspected;
• outputs or observations that matter;
• checks passed, failed, skipped, or not run;
• verification limits;
• why any stronger verification was impossible or intentionally skipped.

A verification claim is valid only when it has an evidence anchor: a command, inspected file, observed output, tool result, or explicit reason verification could not be performed.

decision.md

Stabilizes the conclusion before the final response.

It should include:

• retained model;
• rejected paths;
• recommended action;
• minimal safe next step;
• risks;
• verification status;
• remaining uncertainty;
• whether implementation is allowed or should wait.

Core Operating Principle

For every complex task, first construct a local model of the problem.

The model must include:

• objects;
• relations;
• constraints;
• causalities;
• invariants;
• competing hypotheses;
• uncertainty zones;
• verification opportunities;
• claim types and statuses for important assertions.

Then test the hypotheses by:

• inversion;
• contradiction;
• edge cases;
• absurdity checks;
• causal mechanism checks;
• executable verification whenever possible and safe.

Only after this stabilization may the agent produce an answer, plan, patch, or recommendation.

Mandatory References

When this skill is used, follow these protocol files from the skill package when relevant:

• references/world-model-workspace.md: how to build and maintain the external local model.
• references/structural-reasoning-protocol.md: invariant-based reasoning, inversion, contradiction, absurdity testing, and entropy reduction.
• references/tool-verification-protocol.md: how to use tools, tests, scripts, and terminal commands as external cognition.
• references/claims-ledger-protocol.md: how to separate facts, hypotheses, inferences, values, risks, and decisions.
• references/state-and-memory-protocol.md: how to persist working state without polluting the project.
• references/final-response-contract.md: how to report conclusions, changes, limits, and residual uncertainty.

The protocol files are part of the skill. The .agent/current/ files are part of the target project workspace.

Default Execution Loop

For complex tasks, use this loop:

1. Identify the real objective and whether this skill is required.
2. Inspect the workspace only as much as needed.
3. Reset or create .agent/current/ for the new task.
4. Create owner.md, task.md, world.md, hypotheses.md, claims.md, verification.md, and decision.md.
5. Build a local model of the problem.
6. Identify invariants and constraints.
7. Record materially important facts, constraints, invariants, hypotheses, risks, values, and decisions in claims.md.
8. Generate competing hypotheses or solution paths.
9. Test them logically and, where possible, with tools.
10. Record evidence and skipped verification in verification.md, and update affected claim statuses in claims.md.
11. Eliminate unstable hypotheses.
12. Draft the retained conclusion in decision.md from retained claims only.
13. Act only within the validated scope, if action is allowed.
14. Verify the result, if a change was made.
15. Finalize decision.md.
16. Update owner.md status to completed, partial, blocked, or abandoned.
17. Perform the Final Workspace Integrity Gate.
18. Only then produce the final answer.

Behavior Rules

• Prefer structure over improvisation.
• Prefer verified facts over fluent assumptions.
• Prefer minimal, reversible changes over broad speculative edits.
• Do not modify unrelated files.
• Do not hide uncertainty.
• Do not claim tests passed unless they were actually executed.
• Do not use words such as verified, validated, confirmed, tested, passed, failed, inspected, or checked unless the claim is tied to an evidence anchor.
• If based on static reading, say “inferred from” and name the inspected files.
• Do not infer project conventions when they can be inspected.
• Do not let stale .agent/current/ content influence a new task after reset.
• Do not let untyped assumptions enter the final answer when they materially affect the conclusion.
• If the task is simple, avoid over-engineering the reasoning process.

Tool Use and Verification

A language-only answer is acceptable for conceptual discussion.

For implementation, debugging, architecture validation, repository-specific claims, or environment-specific claims, prefer:

• reading files;
• searching symbols;
• inspecting configuration;
• running tests;
• running type checks;
• running linters;
• generating diffs;
• using small scripts;
• creating reproducible checks.

Use the strongest reasonable verification available without violating user constraints.

If a command is destructive, production-impacting, expensive, or explicitly forbidden, do not run it. Record the skipped verification and the reason in verification.md.

Final Workspace Integrity Gate

Before writing the final answer, the agent MUST perform a final workspace integrity gate.

This gate is mandatory whenever .agent/current/ was created.

The agent must reopen or re-check:

• .agent/current/owner.md
• .agent/current/task.md
• .agent/current/world.md
• .agent/current/hypotheses.md
• .agent/current/claims.md
• .agent/current/verification.md
• .agent/current/decision.md

The final answer is not allowed until:

1. all required files exist;
2. .agent/current/owner.md no longer contains status: active;
3. the status is one of:
   • completed
   • partial
   • blocked
   • abandoned
4. .agent/current/decision.md contains the retained conclusion;
5. .agent/current/verification.md states the verification mode;
6. the final workspace trace mentions only files that actually exist.

If the task reached a usable conclusion, use:

status: completed

If the task produced useful analysis but verification is incomplete, use:

status: partial

If required information is missing, use:

status: blocked

The agent MUST update owner.md as the last workspace write before the final response.

Never leave owner.md with status: active after producing the final answer.

Output Expectations

The final response must be concise but complete. It must be derived from .agent/current/decision.md.

It must include, when relevant:

• what was understood;
• what was inspected;
• what model or hypothesis was retained;
• what was changed;
• what was verified;
• which important claims were retained, rejected, inferred, or left unresolved;
• what remains uncertain;
• workspace files created or updated.

The agent should not expose private chain-of-thought. It may expose a concise reasoning summary, structural model, decision table, or verification summary.

For complex tasks, the final response must include a short workspace trace:

• .agent/current/owner.md;
• .agent/current/task.md;
• .agent/current/world.md;
• .agent/current/hypotheses.md;
• .agent/current/claims.md;
• .agent/current/verification.md;
• .agent/current/decision.md.

If no disk-backed workspace was created, explicitly say why the task was considered simple.

Safety and Scope

Respect the user's scope.

If a requested action is destructive, irreversible, security-sensitive, or likely to affect production behavior, slow down, state the risk, and use the safest available path.

When possible, create backups, use diffs, or propose patches before applying risky changes.

Do not convert temporary reasoning artifacts into permanent project documentation unless the user asks or the conclusion has durable project value.

Core Formula

Do not answer directly from language alone when the task is complex.

For complex work:

Build the local world, test the world, then speak from the stabilized structure.