set-context

Files (1)

• SKILL.md

SKILL.md (first lines)

# fsad-harness:set-context — Context-Gathering Subskill

Gather everything a downstream planning pass needs — codebase shape plus the initiative's own
boundaries — and emit it as a single `context.md` file. Nothing else reads or writes to disk in
this skill besides that one file (and, when graphify runs, whatever `graphify-out/` it produces).

## Asking the user

This rule covers every question this skill asks the user: a confirmation, a choice, a missing value, a numbered decision list, or a stop-and-ask. It applies even where a later step says "ask the user" or "ask exactly once". The user may watch the decisions pane rather than the chat, so a question that only goes to chat can go unanswered.

- **When `mcp__decision-tracker__decision` is in your tool list** (loaded, or named as a deferred tool; load a deferred one with `ToolSearch` first), log each question before you ask it:
  1. Call it with `action: "open"`, the question (ending in `?`), and `options` when the answers are a closed set. Set `required: false` when the work can go on without an answer. A numbered list of questions opens one decision per item. Keep each returned `id`.
  2. Ask the question in chat as this skill says. The open call does not replace the chat question.
  3. When the user answers, in chat or as a `Decision Dn: <answer>` message from the plugin, call the tool with `action: "close"`, the `id` and the answer.
  4. When the change the answer asked for is in place, call it with `action: "implement"`, the `id` and a `path:line`.
- **When the tool is absent**, ask in chat only.
- An `AskUserQuestion` call is logged on its own. Do not open it again.
- This rule changes where a question is logged. It does not change when this skill asks, or how many times.

## Invocation model — read this first

**This skill runs inline**, in the same conversational turn as the interactive user, for every
piece of user-facing interaction below: every targeted question in Step 3, and any question
graphify itself needs answered (its corpus-size subfolder prompt, its package-install notice).

Invoking graphify's build **may** be dispatched via the `Agent` tool as a subagent when that's
useful — e.g. to isolate a long-running corpus scan while you keep the turn free. But if that
subagent hits graphify's own interactive pause (its >2,000,000-word / >500-file subfolder
question) or its package-install step, **it must stop and report back to this inline turn rather
than resolve the question itself** — you relay it to the user, get the answer, and resume the
subagent with it. A subagent that cannot relay is not a valid way to invoke graphify from this
skill; if you can't guarantee that relay (e.g. no way to resume the dispatched agent with an
answer), run graphify inline instead.

## Step 1 — Resolve the target

Determine the target repo/scope:
- If an explicit path argument was given, use it.
- Otherwise use the current working directory.

Confirm the resolved path to the user in one line before continuing: *"Gathering context for
`{target}`."*

## Step 2 — Codebase context: graphify or manual sweep

1. Check whether `{target}/graphify-out/graph.json` already exists.
   - **Exists** — this is a **query**, not a build. Run `graphify query "What is this codebase's
     overall architecture and module structure?"` against it. Record the answer's key points in
     `context.md` under Codebase Context, and note explicitly that this came from an existing
     graph (`graphify-out/` was already present — no build was run).
   - **Does not exist** — check whether the `graphify` skill is installed locally
     (`~/.claude/skills/graphify/SKILL.md`).
     - **Installed** — offer to run a graphify build against `{target}` (or dispatch it via
       `Agent` per the invocation model above). **Tell the user before graphify installs
       anything or before its corpus-size question could fire** — don't let either happen
       silently:
       - Graphify's own Step 1 checks whether its `graphifyy` package is installed and installs it
         via `uv tool install` / `pip install` if missing. Say so before triggering that step:
         *"graphify needs its package installed first if this is the first time it's run on this
         machine — that'll happen automatically."*
       - If graphify's corpus-size check trips (>2,000,000 words or >500 files), it will ask which
         subfolder to scope to. Surface that question to the user directly the moment it fires —
         do not let it silently stall this "mandatory, non-skippable" step.
       - Once the build finishes, record a summary of what it found in `context.md` under Codebase
         Context, and note that this came from a fresh build.
     - **Not installed, or the user declines the offered build** — fall back to a manual context
       sweep: repo structure (top-level layout), existing docs (README, CLAUDE.md, ADRs), package
       manifests (package.json / pyproject.toml / etc.), recent git history (`git log
       --oneline -20`), and any existing `planning/` artifacts. Record findings under Codebase
       Context and note explicitly that no graphify graph was used.

## Step 3 — Targeted questions

Ask the user each of the following that graphify or the manual sweep couldn't already answer.
Ask **one at a time**, not as a form. Record every answer in `context.md` — a question asked but
never carried into the file is not actually gathered.

1. **Initiative slug/name** — the name used to derive the output directory (see `fsad-harness:plan`'s Step
   4 slug-transform algorithm: lowercase, non-alphanumeric runs collapsed to a single hyphen,
   leading/trailing hyphens trimmed — e.g. "Auth Service Refactor!" → `auth-service-refactor`).
2. **Scope boundaries** — what's in scope for this initiative, and what's explicitly out.
3. **Non-negotiable constraints** — technical, business, timeline, or behavior-preservation
   constraints that must hold no matter what the plan proposes.
4. **Stakeholders** — who cares about this initiative's outcome, and who needs to sign off.
5. **Target repo** — confirm whether the plan ships to this same repo or a different one (for
   example, a plan authored in one repo that targets another).
6. **Versioning/release conventions** — the target repo's versioning scheme and release process,
   if not already discoverable from the codebase sweep above.

If the user says "use your best judgment" for any of these, record a stated assumption in
`context.md` rather than blocking — but always record something; never leave a question answered
only in the conversation and not in the file.

## Step 4 — Emit context.md

Write a single structured `context.md` to `planning/plan/<slug>/` (using the slug from Step 3.1
and the transform above), or to a scratch location — e.g. the repo root — if that directory
doesn't exist yet (it's created once the initiative is confirmed, in `fsad-harness:plan`'s Phase 0).

**Why a file, not an in-memory handoff:** every downstream drafting agent (`fsad-harness:plan`'s Phase
1-4.5) is a separately-dispatched `Agent`-tool subagent with no memory of this skill's own turn —
only a file survives across that boundary. Every downstream drafting agent's dispatch prompt must
reference this file's path rather than re-deriving context independently; that's on `fsad-harness:plan`, not
this skill, but it's why this file's shape has to be complete on its own.

Template:

```markdown
# Context — {initiative name}

## Codebase Context
[Summary from graphify query, graphify build, or manual sweep — and which of the three produced
it]

## Initiative
- **Slug:** {slug}
- **Scope boundaries:** {answer}
- **Non-negotiable constraints:** {answer}
- **Stakeholders:** {answer}

From tbeack/fsad_playbook, MIT.

More from tbeack/fsad_playbook