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:

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:

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.