Fog

Fog

Fog is the gap between the map (prompt, plan, assumptions) and the territory (codebase, APIs, real constraints, user taste). The ledger makes fog visible and burns it down to a defined end.

The ledger

One file per task: FOG.md, next to where the work happens (or where the user says). When a second task joins the directory, rename the existing ledger to FOG-.md before creating the new one, also slugged.

# FOG: 

## Open
- [KU]  → lookup
- [KU]  → ask
- [UK]  → show
- [UU?]  → scout

## Assumed
- [A]  — cost to revisit: 

## Resolved
- [x]  (, ) — 

## Deviations            
- 

territory covers anything verified against the real system, including your own experiments. Each arrow names the resolver: → lookup you do yourself; the rest are the matching fog-* skill.

Quadrants and their resolvers

| Tag | Fog type | Resolver | |---|---|---| | — | Known known | Not fog. Straight into the spec. | | KU | Known unknown, fact | → lookup — the territory answers it. Never ask what code or docs can answer. | | KU | Known unknown, decision | → ask (fog-ask) | | UK | Unknown known — taste, recognized only on sight | → show (fog-show) | | UU? | Suspected unknown unknown | → scout (fog-scout) | | A | Low-risk residue | Take the most reversible default and label it. |

Rules

• Every open item carries its resolver. The ledger is a work queue, not a diary.
• Burn-down is visible. Announce open, assumed after every ledger write. Planning is complete when every open item is resolved or converted to a labeled assumption.
• Assumptions are vetoable, not silent. Present them as one batch; never interleave with blocking questions.
• Resolved keeps its why — decisions and territory findings that shaped the plan. A finding shaped the plan only if a later step would act differently knowing it; the rest is dropped.

Lifecycle

• Birth: any fog-* skill that would write to a missing ledger (or section) creates it first.
• Handoff: the ledger plus the persisted plan (see fog-plan) is the launch packet — hand both to any fresh context or subagent.
• Death: after the task's acceptance gate (merge, sign-off, or delivery) passes, graduate the whys that are hard to reverse or surprising without context into ADRs, docs, or the commit message, then delete the ledger. It is working memory, not documentation.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: leoncuhk
• Source: leoncuhk/defog
• License: MIT

Install and usage instructions live in the source repository linked above.