# Capability Scan

> Bootstrap a capability's documentation folder from the codebase — research the services that implement it with parallel Explore agents, write the first Arbeitsdokument describing the current state, and propose ADR candidates for decisions visible in the code. Use when a capability exists in code but has no note yet, when starting documentation for an undocumented service or bounded context, or when the user asks to document an existing system from scratch.

- Skill: `jo-bity/capability-scan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jo-bity/capability-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jo-bity/capability-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Jo-bity (https://skillmd.com/u/jo-bity)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jo-bity/capability-scan

---


> **Style:** Focus on conciseness in your output. Stay brief, but never sacrifice semantics (meaning) for conciseness.

# Capability Scan

The on-ramp into the documentation loop. `capability-doc` *updates* an existing note; this skill
produces the **first** one, read out of the code rather than out of an interview.

Output: a capability folder with a populated Arbeitsdokument, plus a list of **ADR candidates** for
the user to run through `adr-log`. It does not write decision records itself — see the hard rule
below.

## Configuration

`$OBSIDIAN_VAULT` is the vault root. Resolve it before writing; if unset, ask once and offer to
record it in the user's `CLAUDE.md` / `AGENTS.md`. The default folder for engineering work is
`02_Entwicklung/` — adapt to the vault's actual scheme.

## Step 1 — Fix the scope

Establish, asking only what the codebase cannot answer:

1. **The capability name.** The name the team uses, not the service name (`KYC`, not `kyc-service`).
2. **Where it lives.** Which services, bounded contexts, modules and config implement it.
3. **The boundary.** What is deliberately *not* part of it. Without this the note grows without end.

Check the vault first: if `02_Entwicklung/<Capability>/` already exists, stop and hand over to
`capability-doc` — this skill only bootstraps.

## Step 2 — Research in parallel

Launch one Explore agent **per service, bounded context or concern**, not one for everything. Each
gets a narrow brief and returns findings, not file dumps.

Cover, where they exist:

| Area | What to bring back |
|---|---|
| Domain model | Aggregates, entities, value objects, the state machine and its transitions |
| API surface | Endpoints, their contracts, auth/policy annotations, OpenAPI specs |
| Integrations | Connectors, clients, events published and consumed, protocols and URI schemes |
| Persistence | Tables/collections, ownership, what is system of record and what is a cached copy |
| Configuration | Per-partner/tenant config keys, feature flags, lookup keys |
| Tests | What the tests assert is true — often the only written statement of a rule |

Read actual code. Every claim in the note must be traceable to a file.

Wait for all agents before writing.

## Step 3 — Write the Arbeitsdokument

Create `$OBSIDIAN_VAULT/02_Entwicklung/<Capability>/<Capability> — Arbeitsdokument.md`:

```md
ADRs: [[02_Entwicklung/<Capability>/ADR/|ADR-Ordner <Capability>]]

> **Stand:** DD.MM.YYYY — *gepflegt von Claude (skill: capability-scan)* #claude-generated #skill/capability-scan

# <Capability> - Working Document

## Überblick
{1 Absatz: was die Capability ist, wer sie owned, Scope-Grenze}
{genau EIN Mermaid-Systemkontext-Diagramm}

## Fachliche Anforderungen
{Verhalten, Regeln, Zustände, Verträge — was das System fachlich tut}

## Technische Anforderungen
{Architektur, BC-Platzierung, Integrationen, Datenhaltung, Security — wie es umgesetzt ist}

## Offene Punkte
{Was der Code nicht beantwortet hat. Je Punkt: wen fragen.}

## Verwandte Notizen
{eine Zeile, ·-separiert, Rollen-Klammer je Link}
```

Rules:

- **Current state only.** What the code does today. No history, no roadmap, no dates in the body.
- **Fachlich vs. technisch:** a rule's *meaning* is fachlich, its *mechanism* is technisch. When a
  fact straddles both, put the rule fachlich and the mechanism technisch — never duplicate.
- **Mermaid liberally.** The Überblick context diagram is mandatory; add `stateDiagram-v2` for a
  lifecycle and `sequenceDiagram` for a cross-service flow where they exist. 3–8 nodes, labelled
  edges, real names from the code so the diagram doubles as a map back into it.
- **Precise, not verbose.** Target ~150–250 lines. Every sentence checkable against code or config.
- German prose; code/API/state identifiers untranslated in backticks.
- `[[wikilink]]` any related note already in the vault — scan the folder before finishing.

## Step 4 — Propose ADR candidates

**Hard rule: do not write decision records.** Code shows *what* was decided; it almost never shows
*why*, and a decision record without its rationale is worse than none — it looks authoritative and
teaches nothing. Inventing a plausible reason is the specific failure to avoid.

Instead, list the candidates for the user, each as one line: the decision as observed, the file that
shows it, and the question only a human can answer.

```
- Connector lives in `billing-service`, not in the calling service
  → services/billing/connectors/PaymentConnector.java
  → Why there? What was rejected?
```

Apply the decision-record bar — all three must hold, otherwise it is not a candidate:

1. **Hard to reverse** — changing it later costs something real
2. **Surprising without context** — a future reader would ask "why this way?"
3. **Real trade-off** — genuine alternatives existed

Typical candidates: boundary and ownership choices, integration patterns between contexts,
technology picks with lock-in, deliberate deviations from the obvious path, constraints that are
invisible in the code itself.

Not candidates: behaviour (belongs in the note), reversible defaults, the obvious thing done for
obvious reasons.

## Step 5 — Close

Report: the folder and file created, which services were scanned, how many candidates were found,
and what the code could not answer. Then offer to run `adr-log` to turn the candidates into decision
records — that is the next step in the loop.