barcelosvinicius Skill: Structural Analysis Pipeline
What this skill is
Defines a repeatable multi-phase pipeline for analysing the structure of any
software project. The output is a living docs/structural-analysis.md that maps
every module to an architectural layer, records dependencies, highlights risks,
and tracks improvement items — giving AI agents and humans a shared structural
map of the codebase.
Inspired by the multi-agent approach of the Understand-Anything project (static analysis + LLM semantic enrichment in specialised passes), adapted for the basic-engineering doc system.
Activation edges
| Type | Target | When |
|---|---|---|
invoke |
proc-domain-mapping |
Phase 4 — it owns the ## Domain map section and its schema |
When to run this pipeline
| Trigger | Description |
|---|---|
| Project kickoff | Before the first sprint begins — baseline the architecture |
| Post-major refactoring | After merging a structural change to reset the map |
| Onboarding preparation | Before adding a new team member or AI agent |
| Architecture review session | When drift between code and docs is suspected |
| Incremental update | Re-run only phases 2–4 for files changed since last run |
Pipeline overview
Phase 1 — Project scan
↓ discover files, languages, frameworks, entry points
Phase 2 — File-level analysis
↓ extract functions, classes, imports, exports per file
Phase 3 — Architecture analysis
↓ assign each module to a layer, detect coupling, identify boundaries
Phase 4 — Domain extraction
↓ map modules to business concepts and flows
Phase 5 — Review and assembly
↓ validate completeness, cross-check references, output structural-analysis.md
Phase 1 — Project scan
Goal: produce a complete inventory of what exists in the project.
Checklist
- List all source directories and their purpose
- Identify languages, frameworks, and main libraries (from manifests:
pom.xml,package.json,requirements.txt,go.mod, etc.) - Identify entry points:
main(), API routers,@SpringBootApplication, etc. - List configuration files and what they control (
.env.example,application.yml,Dockerfile, CI workflows) - Note the build toolchain and how to run the project locally
Output
Schema in output-schemas.md.
Phase 2 — File-level analysis
Goal: extract structural facts from each source file.
For each file, record:
| Field | What to extract |
|---|---|
path |
Relative path from project root |
layer |
api · service · domain · data · ui · util · config · infra |
exports |
Public functions, classes, interfaces |
imports |
External dependencies and internal module references |
description |
One-sentence plain-English summary of the file's purpose |
patterns |
Notable patterns: Repository, Factory, Strategy, Observer, etc. |
risks |
Code smells or security flags visible from structure alone |
Layer assignment heuristics
Keyword-to-layer table in output-schemas.md.
Incremental update rule
Store a fingerprint (SHA-256 of file content) for each analysed file. On re-run, skip files whose fingerprint has not changed — only process files added, modified, or deleted since the last run.
Phase 3 — Architecture analysis
Goal: map the module graph, identify coupling violations, and surface risks.
Coupling analysis
For each module pair (A → B), record:
- Direction: A depends on B (not the reverse)
- Type: compile-time, runtime, or configuration
- Violation flag: does A depend on a layer it should not? (e.g.,
ui→data)
Allowed dependency directions (strict):
api → service → domain ← data
config → any
util ← any
infra ← service
Any arrow that crosses layers in the wrong direction is a coupling violation and must be recorded as a pending item.
Architecture risks checklist
- Circular dependencies between modules
- God classes / God services (single file with > 400 LOC or > 10 public methods)
- Direct database access from api or ui layers
- Business logic in controllers or repositories
- Missing abstraction boundaries (e.g., external API client used directly in service)
- Hardcoded configuration (URLs, credentials, size limits)
- Missing error boundaries on entry points
- Missing health check endpoint
Phase 4 — Domain extraction (delegated)
Goal: map code to business concepts, flows, and process steps.
This phase is owned by proc-domain-mapping. invoke it and use its output
as this pipeline's ## Domain map section. Never restate its schema here —
two skills prescribing one section is a contradiction with a delivery date: the
one that runs last wins and neither knows the other exists.
If the project has no domain complexity worth a bounded-context analysis, say so in one line and leave the section at that. An empty section with a reason beats a schema invented on the spot.
Phase 5 — Review and assembly
Goal: validate the analysis and produce the final document.
Validation checklist
- Every source file is assigned to exactly one layer
- All internal imports resolve to known files (no dangling references)
- Every coupling violation has been recorded as a pending item
- Domain flows are complete: each step maps to a real file
- All risks from Phase 3 are either explained or flagged as items
Output — structural-analysis.md
Use the base template templates/docs/structural-analysis.template.md. The
mandatory section list is in output-schemas.md; §0 (the
verifiable fact panel) comes first, before any prose.
Incremental update (post-release)
When re-running after a change rather than a full new analysis:
- Load existing
structural-analysis.md - Run Phase 2 only on files whose fingerprint changed
- Re-run Phase 3 coupling analysis only for modules that gained/lost imports
- Update Phase 4 domain map only for affected domains
- Update the pending items list: close resolved items, add new ones
- Update
## Analysis metadatawith the new date and changed file count
Output quality checklist
Before committing docs/structural-analysis.md:
- Executive summary is accurate and readable by a non-engineer
- All layers are populated (no empty sections)
- §0 exists, is the first section, and every row has a command and a date
- Percentages and counts in the prose appear in §0 with their command — an "engineering estimate" that no command reproduces does not belong here
- Pending items are numbered, have severity ratings, and each one states "done when" (by command) and "blocked by" — an item with no finish line is a feeling and will reappear in every future analysis
- Module map can be rendered (valid Mermaid or clear indentation)
- Metadata section is updated with today's date
- File was committed alongside any code changes that triggered it
Size verdict
Q1 — does the trigger split? No: kickoff, post-refactoring and
documentation-divergence all produce one artefact. Q2 — what is lookup? The
output schemas and the layer-keyword table, now in output-schemas.md. What
remains is the five-phase procedure, and it stays at ~200 lines by design — the
~150 budget is an alarm, not a verdict, and a pipeline is what it costs.
Resources
- output-schemas.md — the document skeleton, the layer assignment table, and the Phase 1 scan schema.
See also: the proc-domain-mapping and proc-impact-analysis skills.