characterize-brownfield

name

characterize-brownfield

description

Use to reverse-engineer an existing/brownfield codebase into structured, confidence-scored characterization artifacts (tech stack, feature inventory, dependency & integration map, existing API contracts, test-coverage traceability, tech debt & risks). Use before composing a PRD, or standalone to understand a legacy system with no docs. Activate on 'characterize this codebase', 'what does this system do', 'map the architecture', 'find existing contracts', 'assess tech debt', 'reverse-engineer this legacy system'.

Characterize Brownfield

Reverse-engineers an existing codebase into structured, confidence-scored artifacts. Every claim is either a FACT (from a tool call — S7) or an INFERENCE (LLM interpretation), and every inference carries a confidence: High (directly observed, e.g. a parsed OpenAPI file) / Medium (inferred from strong signals, e.g. route patterns + naming conventions) / Low (guessed from weak or absent evidence). Honesty about confidence is the point — a brownfield PRD built on fabricated certainty is worse than one that says "unknown."

Boundary. Read-only. Never edits code. Does not write a PRD (see compose-brownfield-prd). Does not create issues or stories.

Inputs

• Repository path (required).
• Depth: quick (2-5 min, pattern-based, no source reads) / deep (10-30 min, critical dirs — default) / exhaustive (30-120 min, all source, opt-in only — warn the user of cost first).
• Focus directories (optional) — narrows deep/exhaustive scans.

Procedure

1. Structure & stack (FACT, via tool calls — S7 only, never recall)

• find . -maxdepth 3 -type d (or workspace tools) for top-level layout.
• Read manifest files present: package.json, *.csproj/*.sln, requirements.txt/pyproject.toml, pom.xml/build.gradle, go.mod, Cargo.toml. Extract exact framework + versions — never guess.
• Read config files present: tsconfig.json, .editorconfig, lint configs, CI workflow files.
• git log --since="90 days ago" --name-only --pretty=format: to find active areas (recent churn correlates with what still matters).

2. Feature inventory (INFERENCE, confidence-scored)

For deep/exhaustive: read entry points (controllers, route files, CLI commands, message handlers). Group into a feature table:

Feature	Evidence	Confidence	Category
{name}	{file:line or pattern}	High/Med/Low	Core / Secondary / Legacy-unused

"Legacy-unused" = present in code but no recent git activity and no inbound references found — flag, do not delete, do not assume dead.

3. Integration & dependency map (FACT where possible)

List outbound calls (HTTP clients, DB connections, message queues, third-party SDKs) found via grep for client instantiation patterns, connection strings, appsettings*/.env* keys (names only — never read secret values). Each entry: target system, protocol, confidence.

4. Existing API contracts (opt-in facet, graceful degradation)

Search for OpenAPI/Swagger/AsyncAPI/Pact files (*.yaml/*.json matching openapi:/swagger:/ asyncapi:, pacts/*.json) and framework-generated specs (Swashbuckle/NSwag output routes, springdoc, FastAPI /openapi.json route). Light-weight v1: discover + summarize (endpoint list, methods, request/response schema names) — not full schema validation. If none found, record contracts: none-found and move on; this is optional, never a blocker.

5. Coverage traceability (opt-in facet)

For each feature in the inventory, check test coverage: search for test files referencing the feature (by name, route, or class). Classify FULL (direct test asserting the behavior) / PARTIAL (indirect coverage, e.g. integration test exercises the path but doesn't assert the specific behavior) / NONE. When zero tests exist for a feature, use a synthetic oracle: infer expected behavior from the code itself (read the implementation, describe what it currently does) and mark confidence Low — this still gives downstream steps something concrete instead of a blank. Never claim FULL coverage without reading an actual assertion.

6. Risk scoring (3x3 model)

For each tech-debt item or gap found (missing tests, undocumented integration, outdated dependency, NONE coverage on a Core feature): score probability x impact = 1-9 (1-3 each axis). Map: 9 -> P0 (auto-flag BLOCK), 6-8 -> P1, 4-5 -> P2, 1-3 -> P3. Action per band: P0 = BLOCK (escalate), P1 = MITIGATE, P2 = MONITOR, P3 = DOCUMENT.

7. Confidence gate (S4 — before writing artifacts)

Compute an overall confidence distribution (% High / Med / Low across all inferences) and a coverage summary (% features with FULL/PARTIAL/NONE traceability). Verdict:

• PASS — majority High confidence, no Core feature at NONE coverage with P0/P1 risk.
• CONCERNS — meaningful Medium/Low share, or NONE coverage on a P1+ risk item.
• FAIL — majority Low confidence or critical structure (stack/entry points) unresolved.

CONCERNS or FAIL: surface an explicit validation checklist to the human (list every Low-confidence claim and every NONE-coverage Core feature) before proceeding. This is a quality checkpoint, not a security gate — the human confirms or corrects, then work continues.

Outputs

Written under .copilot-tracking/skraft-plans/{projectSlug}/characterization/{YYYY-MM-DD}/ (see plugins/skraft-framework/instructions/skraft-artifacts.instructions.md for the path root; this workflow is standalone and does not claim a pipeline phase row):

• index.md — summary, confidence distribution, coverage summary, gate verdict.
• structure.md — stack, versions, layout (FACT).
• features.md — feature inventory table.
• integration.md — dependency/integration map.
• contracts.md — discovered API contracts (or none-found).
• coverage.md — traceability table (FULL/PARTIAL/NONE per feature).
• tech-debt.md — risk-scored gaps (3x3 table).

Every file starts with <!-- markdownlint-disable-file -->. Every claim in every file carries its confidence tag inline, e.g. (confidence: Medium — inferred from route naming).