---
name: surveying-capabilities
description: Survey what the local machine can actually do and bind each abstract capability a task needs to a concrete provider — an installed skill, an MCP tool, a CLI, or a subagent — before any plan is written. Use before planning multi-step work, when you need to know what tooling exists (有什么工具 / 本机能力 / 装了哪些技能 / 能不能做), or when a step fails because something is missing. Introspects your own context first at zero cost, then probes only what the task requires. Produces .superclarity/environment.md and .superclarity/<task>/capabilities.md, including an explicit list of capability gaps. Do NOT use for trivial single-step tasks, and do NOT use to enumerate the whole machine when the provider is already confirmed.
license: MIT
metadata:
  pack: superclarity
  phase: survey
---

# Plan against the machine you have

A plan that assumes a tool this machine lacks is not a plan, it is a wish. It fails halfway through, after the expensive steps, when replanning costs the most.

The opposite failure is just as common: the machine has a specialist skill for exactly this work, the agent never looks, and reinvents a worse version by hand.

This skill closes both gaps by resolving abstract capability needs to concrete local providers before anything is planned.

Answer the user in whatever language they wrote in.

## The two layers

```
Task needs a capability      capability: web-research
            |
            |  resolved here, against this machine
            v
Bound to a real provider     provider: <a research skill that is installed>
                             fallback: fetch tool + user-supplied URLs
```

Skills stay portable because they never name a tool. Plans become concrete because every step names one.

## Procedure

**1. Introspect first — it is usually free.** Most harnesses already give you your tools, your installed skills and their descriptions, and your subagents. Read that before spending a turn on anything else.

If your harness does *not* expose one of those lists, say so and probe for it instead. Absence from your context is not proof of absence from the machine — treating it as proof manufactures false capability gaps, which is the same error this pack forbids everywhere else.

**2. Derive needs from the brief.** List the capabilities this task requires, using [the taxonomy](references/capability-taxonomy.md). The list is closed — fourteen entries. If a need does not fit one, the step is probably two steps.

**3. Probe only the gaps.** For each need with no provider visible from context, run the smallest read-only check that settles it. Recipes, including per-OS commands and where each harness keeps its config, are in [probe recipes](references/probe-recipes.md). Do not enumerate the machine.

**4. Resolve, with a fallback each.** Every needed capability gets a provider and a fallback, or is marked a gap.

**5. Write it down.** `environment.md` at the workspace level with a `surveyed_at` timestamp; `capabilities.md` inside the task directory for this task's resolution.

## Resolution table

```markdown
| Capability   | Provider                        | Confidence | Fallback                     |
| ------------ | ------------------------------- | ---------- | ---------------------------- |
| web-research | <installed research skill>      | confirmed  | fetch tool + user URL list   |
| data-transform | jq (on PATH)                  | confirmed  | manual, sample only          |
| cloud-ops    | none                            | GAP        | emit commands for the user   |
```

Confidence is `confirmed` (seen in your context or probed just now), `assumed` (config declares it but unverified), or `GAP`. Never record `assumed` as `confirmed` — an assumed provider fails at the step that needs it, which is the worst moment to discover the truth.

**An `assumed` provider is not plannable.** Before the plan is written, every `assumed` entry must become `confirmed` by a probe, or be treated as a `GAP` and put to the user. Carrying an assumption into a plan is how a task fails after the expensive steps.

Presence is not readiness: an installed cloud CLI that is not logged in is still a gap for any step that calls it. Where a step depends on authentication, an account, a quota, or a permission scope, confirm that specific thing rather than the binary's existence.

## Routing to specialists is mandatory

If an installed skill matches the domain, the plan goes through it. Improvising a hand-rolled substitute for a capability the machine already has is a defect, not a style choice.

Two guards on this:

- **Do not invent tooling.** A provider that is not confirmed present does not exist for planning purposes.
- **Do not infer behaviour from a description.** A description says what a skill claims to cover. Before routing real work through it, load it and read how it actually behaves.

## Gaps are decisions, not silence

When a needed capability has no provider, never quietly downgrade the step. Put it to the user with the consequence spelled out:

1. **Install something** — if a skill-discovery capability is available, offer to search for a fitting skill. Never install without approval.
2. **Supply it manually** — the user provides the data, export, or credentials.
3. **Substitute a weaker method** — say plainly what accuracy or coverage is lost.
4. **Drop it from scope** — and record what the result no longer covers.

Record the decision in the brief's assumptions, and carry every unresolved gap through to the final report's coverage section. A gap that is never disclosed becomes a false claim at delivery.

## Cost discipline

Introspection is free and always runs. Probing is task-scoped, one or two calls. Deep checks happen only after a failure or before an expensive commitment. Cache in `environment.md` and re-survey only when it is stale, a step failed on a missing tool, or the user says the environment changed.

Show the user a finding **only when it changes the plan**. A full inventory recital is noise.

## Worked example

Task: evaluate three CRM vendors and produce a comparison for a buying decision.

Needs: `web-research` for public material, `browse-authenticated` for a gated analyst report, `data-transform` for the scoring matrix, `doc-convert` for the slide deck, `ask-user` for weighting the criteria.

Resolution finds a research skill installed and a spreadsheet-capable runtime available, but no authenticated browsing and no deck generation. Two gaps go to the user: the analyst report either gets pasted in or is dropped from scope, and the deck is delivered as markdown unless they want a manual export step. Both decisions land in `brief.md`, and if the analyst report is dropped, the final report says the comparison omits it — not that the vendors lacked analyst coverage.