discovering-context

Files (1)

• SKILL.md

SKILL.md (first lines)

# Discovering Context

## Overview

Before you can write a good plan, you must know **what you need to know**. This
skill builds a **context dependency graph** — a DAG rooted at the goal whose
nodes are the pieces of context required to plan it, and whose edges are "B is
needed to satisfy A". You interview the user to resolve decisions, add a node
for each piece of context the goal depends on, then ask of **every node**:
*"do I need more context to satisfy this?"* — expanding leaves until the graph
saturates. The converged map is the input to `writing-plans`.

**Core principle:** A plan is only as good as the context behind it. Discover
and structure the context *first*, as a graph, so planning starts from a
complete picture instead of guesses.

**This is the upstream phase.** It composes into the existing flow:

```
discovering-context  →  writing-plans  →  executing-plans
   (this skill)          (the plan)        (the work)
```

**Announce at start:** "I'm using the discovering-context skill to map the
context this goal depends on before we plan it."

## When to Use

- The goal is large, ambiguous, or touches systems/decisions you don't yet understand
- You catch yourself about to plan on assumptions ("I'll just assume they use JWT…")
- Requirements exist but the *unknowns* haven't been enumerated
- Before `writing-plans` on anything non-trivial

**When NOT to use:** a small, fully-understood change with no open decisions —
go straight to `writing-plans`. This is context-cartography, not design
dialogue: for settling *what to build*, that is `brainstorming`; this skill
maps *what you must know* to build it. Run them together on big work
(brainstorm the design, discover the context) — they are complementary, not
duplicates.

## The Loop

```dot
digraph discovering_context {
    "Seed: root = GOAL" [shape=box];
    "Interview one branch\n(batched, recommended answers)" [shape=box];
    "Answer opens new questions?" [shape=diamond];
    "Add/expand nodes\n(each = context needed)" [shape=box];
    "For each node: need MORE\ncontext to satisfy it?" [shape=diamond];
    "Add child node + edge" [shape=box];
    "Two dry rounds\n(nothing new added)?" [shape=diamond];
    "Ask user: anything missing?" [shape=diamond];
    "Write context-map.md\n→ hand to writing-plans" [shape=doublecircle];

    "Seed: root = GOAL" -> "Interview one branch\n(batched, recommended answers)";
    "Interview one branch\n(batched, recommended answers)" -> "Answer opens new questions?";
    "Answer opens new questions?" -> "Interview one branch\n(batched, recommended answers)" [label="yes, recurse"];
    "Answer opens new questions?" -> "Add/expand nodes\n(each = context needed)" [label="no"];
    "Add/expand nodes\n(each = context needed)" -> "For each node: need MORE\ncontext to satisfy it?";
    "For each node: need MORE\ncontext to satisfy it?" -> "Add child node + edge" [label="yes"];
    "Add child node + edge" -> "For each node: need MORE\ncontext to satisfy it?";
    "For each node: need MORE\ncontext to satisfy it?" -> "Two dry rounds\n(nothing new added)?" [label="no"];
    "Two dry rounds\n(nothing new added)?" -> "Interview one branch\n(batched, recommended answers)" [label="no, keep expanding"];
    "Two dry rounds\n(nothing new added)?" -> "Ask user: anything missing?" [label="yes"];
    "Ask user: anything missing?" -> "Add/expand nodes\n(each = context needed)" [label="user names a gap"];
    "Ask user: anything missing?" -> "Write context-map.md\n→ hand to writing-plans" [label="user confirms complete"];
}
```

### 1. Seed
Capture the goal verbatim as the root node `GOAL`. Take a **light** look at the
obvious entry points (README, top-level layout) so the interview isn't blind —
don't spelunk the whole codebase; unknowns become `needs-research` nodes to
resolve later, not exploration to do now.

### 2. Interview relentlessly — batched, one branch at a time
Walk down **one branch of the dependency tree at a time**, resolving decisions
before moving on. Ask with the **AskUserQuestion** tool so the user gets
selection boxes:

- **Every question carries your recommended answer as option 1**, labeled
  `(Recommended)`, with a one-line reason in its description.
- Batch the questions that belong to the *same branch* into one call (up to 4).
- **If an answer opens new questions, recurse** — ask the follow-ups before
  leaving the branch. Keep going until that branch is fully understood, then
  move to the next. Relentless means: no open decision left implicit.
- Open-ended questions with no discrete options → ask in prose, still with a
  recommended answer. (Hybrid is fine; prefer the boxes.)

Never plan on an unstated assumption. If you would have to assume it, it is a
node.

### 3. Build & expand the graph
Each resolved-or-open piece of context becomes a **node**. Draw an **edge
`A → B`** when B is context required to satisfy A. Then apply the recursion that
makes this a graph and not a checklist:

> For **every** node ask: *"Do I have enough to plan this, or does satisfying
> it depend on context I haven't captured yet?"* If more is needed, add a
> **child node + edge** and repeat on the child.

Example: `GOAL → auth` → satisfying `auth` needs `session-store` → which needs
`current-infra` (research node) and `data-retention-policy` (user-input node).
Keep descending each branch until its leaves pass the **leaf test**.

**The leaf test — a node may stop expanding ONLY when it is one of:**
- **(a) a decision** with a small enumerable option set AND your recommended default,
- **(b) a fact** answerable by reading specific code/docs/config (name the source), or
- **(c) a requirement** with a concrete, **measurable target value** (a number, not "fast" — "p95 remote apply < 250ms").

A question with no answer path is **not** a leaf. Expand **every branch to the
same standard** — the failure mode is descending deep on the interesting branch
(the core algorithm) and leaving the tedious ones (security, migration, ops,
a11y) one level shallow. If a branch feels boring, that is not permission to
stop early.

### 4. Saturate, then confirm
Keep looping steps 2–3 until **two consecutive rounds add no new nodes**
(auto-saturation — the graph has stopped growing). Saturation is not "the shape

From uhstray-io/huhhb, MIT.

More from uhstray-io/huhhb