| name | ctx-architecture-enrich |
| description | Enrich architecture artifacts with code intelligence data. Takes existing /ctx-architecture output as baseline, verifies and quantifies with GitNexus MCP (blast radius, execution flows, domain clustering, registration sites). Run after /ctx-architecture, not instead of it. |
| allowed-tools | Bash(ctx:*), Bash(git:*), Read, Write, Edit, Glob, Grep, mcp__gitnexus__*, mcp__gemini-search__* |
Enrich existing architecture artifacts with verified data from
code intelligence tools. This skill reads the output of
/ctx-architecture (which forces deep code reading) and layers
on quantified, graph-backed data that reading alone cannot
efficiently provide.
Design Principle
Reading first, tools second. /ctx-architecture produces
deep artifacts through forced code reading - no code intelligence
tools, no shortcuts. This skill runs AFTER that pass, using the
deep artifacts as a baseline. It verifies, quantifies, and extends
- it never substitutes for reading.
The separation exists because agents take shortcuts when code
intelligence tools are available during analysis. A structural
query returns an answer without opening the file - so the agent
never discovers the operational details (defaults, timeouts, scale
math, edge cases) that only emerge from line-by-line reading. The
tool answers the question asked but prevents discovery of answers
to questions never asked.
When to Use
- After
/ctx-architecture or /ctx-architecture principal has
produced artifacts
- After a code-intelligence MCP has indexed the project
(canonical: GitNexus via
npx gitnexus analyze --embeddings;
equivalents apply their own indexing step) and architecture
artifacts already exist
- When the user says "enrich the architecture", "run enrichment
pass", "add graph data", "quantify the danger zones"
- When DANGER-ZONES.md exists but lacks blast radius numbers
- When CONVERGENCE-REPORT.md shows shallow modules that could
benefit from semantic search
When NOT to Use
- As a substitute for
/ctx-architecture - if no architecture
artifacts exist, run /ctx-architecture first
- When no code-intelligence MCP is connected, or the index is
stale — preflight will catch this
- Immediately after
/ctx-architecture in the same session without
user request - let the user review the base artifacts first
Inputs (Required)
The skill refuses to run if these are missing:
.context/ARCHITECTURE.md - the authoritative architecture map
.context/DETAILED_DESIGN.md (or domain split files) - per-module
deep reference
.context/map-tracking.json - coverage state and confidence scores
The skill checks and warns if these are missing but proceeds
without them:
.context/DANGER-ZONES.md - consolidated danger zones (if absent,
extracts from DETAILED_DESIGN.md danger zone sections)
.context/CONVERGENCE-REPORT.md - convergence state
.context/ARCHITECTURE-PRINCIPAL.md - principal analysis
.context/CHEAT-SHEETS.md - lifecycle flow cheat sheets
Phase 1: Preflight
1.1 Verify Architecture Artifacts
Read the required files listed above. If any required file is
missing, stop and say:
Architecture artifacts not found. Run `/ctx-architecture` first
to generate the baseline, then run this skill to enrich it.
1.2 Verify Code Intelligence Tools
Check each capability silently:
Code-intelligence MCP (required for this skill):
This skill's entire purpose is code-graph-verified enrichment,
so it cannot run without a code-intelligence MCP. The canonical
implementation is GitNexus (mcp__gitnexus__list_repos,
mcp__gitnexus__impact, etc.); equivalents that expose the
same capabilities (symbol index, blast-radius queries, indexed
repo state) work equally well.
- Attempt the smoke-test call for whichever code-intelligence
MCP your toolchain provides
- For GitNexus specifically: also check that the current
project is indexed and compare the index timestamp against
the latest git commit to detect staleness
If no code-intelligence MCP is connected:
This skill requires a code-intelligence MCP (e.g., GitNexus,
sourcegraph-cody, or equivalent). None is connected.
If you have GitNexus, configure the MCP and run:
npx gitnexus analyze --embeddings
If you use a different code-intelligence MCP, configure it
per its docs and re-run this skill.
For GitNexus, if the index is stale (commits after last index):
- ≤ 5 commits behind: warn and proceed.
GitNexus index is slightly stale (last indexed: <date>,
<N> commits since). Proceeding - results may be incomplete
for recently changed code.
- > 5 commits behind: hard stop.
GitNexus index is stale (last indexed: <date>, <N> commits
since). Results would be unreliable.
Run `npx gitnexus analyze` to update, then re-run this skill.
(For non-GitNexus code-intelligence MCPs, apply the same
staleness check using whatever the underlying tool exposes.)
Web-search-with-citations MCP (optional):
- Canonical example: Gemini Search
(
mcp__gemini-search__search_with_grounding)
- Equivalents: Firecrawl, Exa, Tavily, or any MCP that
returns grounded results with citations
- If available: note silently, use for upstream pattern lookups
- If not available: silently fall back to built-in web search
1.3 Read Baseline Artifacts
Read all architecture artifacts into context. Pay attention to:
- Module list and confidence scores from
map-tracking.json
- Danger zone entries from DANGER-ZONES.md or DETAILED_DESIGN.md
- Extension points from DETAILED_DESIGN.md module sections
- Shallow modules (confidence < 0.75) from
map-tracking.json
- Convergence state from CONVERGENCE-REPORT.md
Phase 2: Danger Zone Enrichment
For each danger zone identified in DANGER-ZONES.md (or extracted
from DETAILED_DESIGN.md if no standalone file exists):
-
Run impact analysis on the named symbol:
mcp__gitnexus__impact({target: "<symbol>", direction: "upstream"})
-
Record blast radius:
- d=1 count (direct callers - WILL BREAK)
- d=2 count (indirect dependents - LIKELY AFFECTED)
- d=3 count (transitive - MAY NEED TESTING)
- Affected process/execution flow count
-
Assign verified risk level:
Risk thresholds should consider repository scale. In a small
repo (<1000 files), d=1=4 might be critical. In a large repo
(>10k files), d=1=15 might be routine. When unsure, bias toward
HIGH over MEDIUM.
Guidelines (adjust for scale):
- CRITICAL: d=1 > 10 or crosses 3+ domains
- HIGH: d=1 > 5 or crosses 2 domains
- MEDIUM: d=1 2-5, single domain
- LOW: d=1 ≤ 1, localized
Graph data is a lower bound, not ground truth. Dynamic dispatch,
reflection, config-driven wiring, and runtime registration can
make graphs incomplete. If blast radius seems suspiciously low
for a symbol you know is critical from reading the code, flag:
Risk: HIGH (enriched <date> via GitNexus)
⚠ Possible undercount - dynamic or indirect usage suspected
-
Update DANGER-ZONES.md with enrichment data:
1. **<symbol>** - <original description>
- Blast radius: d=1: N, d=2: N, d=3: N
- Affected flows: <list of process names>
- Risk: HIGH (enriched 2026-03-25 via GitNexus)
- Modification advice: <updated based on blast radius>
Update the summary table with verified risk levels.
Phase 3: Extension Point Enrichment
For each extension point identified in DETAILED_DESIGN.md module
sections:
-
Query the call graph for registration patterns:
mcp__gitnexus__context({name: "<registration function>"})
-
Build a registration inventory:
- All call sites with file:line references
- Count of registrations per pattern
- Any unregistered implementations (defined but never wired)
-
Write or update .context/EXTENSION-POINTS.md:
# Extension Points
_Generated <date>. Enriched via GitNexus call graph analysis._
## Summary
| Pattern | Registration Function | Count | Files |
|---------|----------------------|-------|-------|
| <name> | <func> | N | N |
## By Pattern
### <Pattern Name>
Registration function: `<func>` in `<file>`
Registered implementations:
1. `<impl>` - `<file>:<line>`
2. ...
Unregistered (defined but not wired):
- `<impl>` - `<file>:<line>` (potential dead code or
conditional registration)
Phase 4: Execution Flow Enrichment
-
Read all processes from GitNexus:
READ gitnexus://repo/<name>/processes
-
Select the most significant flows (10-15). Prefer flows
that:
- Share symbols with other flows (high centrality)
- Originate from public APIs or entry points
- Cross multiple domains
Step count alone is not a good signal - a 50-step internal
flow matters less than a 10-step cross-domain API flow.
-
Identify multi-flow hotspots - symbols that appear
in 3+ execution flows are integration points worth knowing
-
Update CHEAT-SHEETS.md with an execution flow index:
## Execution Flow Index (via GitNexus)
_Enriched <date>. These flows are auto-detected from the call
graph and complement the manually written cheat sheets above._
| Flow | Steps | Entry Point | Key Symbols |
|------|-------|-------------|-------------|
| <name> | N | <entry> | <hotspot symbols> |
### Multi-Flow Hotspots
Symbols participating in 3+ flows (high-impact modification
points):
| Symbol | Flows | Location |
|--------|-------|----------|
| <name> | N | <file>:<line> |
Phase 5: Domain Clustering Comparison
-
Read auto-detected clusters from GitNexus:
READ gitnexus://repo/<name>/clusters
-
Read manual domain splits from DETAILED_DESIGN.md (the
domain file index if split, or section headers if monolithic)
-
Compare - surface mismatches:
- Modules that GitNexus groups together but the manual split
separates → potential hidden coupling
- Modules that GitNexus separates but the manual split groups
→ potential artificial grouping
-
Write comparison to ARCHITECTURE-PRINCIPAL.md (if it exists)
or print to terminal:
## Domain Clustering Comparison (enriched <date>)
| Manual Domain | GitNexus Cluster | Match | Notes |
|---------------|-----------------|-------|-------|
| <domain> | <cluster> | yes/partial/no | <mismatch detail> |
### Hidden Coupling (GitNexus groups, manual splits)
- <module A> ↔ <module B>: N calls between them, but in
separate manual domains
### Artificial Grouping (GitNexus splits, manual groups)
- <module A> and <module B>: 0 calls between them, but in
same manual domain
### Boundary Violations
If hidden coupling exceeds 10 calls between manually separated
domains, flag as:
⚠ Architectural boundary violation: <domain A> ↔ <domain B>
N cross-boundary calls - consider refactoring or redefining
the boundary.
Phase 6: Shallow Module Deep-Dive
For each module at confidence < 0.75 in map-tracking.json:
-
Run semantic queries for the module's key concepts:
mcp__gitnexus__query({query: "<module purpose or key concept>"})
-
Get context on key symbols:
mcp__gitnexus__context({name: "<key exported symbol>"})
-
Read process participation - which execution flows does
this module participate in?
-
Update the module's DETAILED_DESIGN.md section with
findings - callers, execution flow participation, cross-module
relationships that reading alone may have missed
-
Update confidence score in map-tracking.json with
justification:
"<module>": {
"confidence": 0.7,
"notes": "Enriched via GitNexus: 12 callers found, participates in 3 flows. Bumped from 0.5.",
"enriched_at": "<ISO-8601>"
}
Only bump confidence if the enrichment genuinely improved
understanding. Adding caller counts without comprehension
does not justify a bump.
Litmus test: if the module's purpose cannot be restated
in 1-2 sentences after enrichment, do NOT increase confidence.
Numbers without narrative are noise.
Phase 7: Update Artifacts
7.1 Update CONVERGENCE-REPORT.md
Re-read map-tracking.json (source of truth) and regenerate
CONVERGENCE-REPORT.md with updated confidence scores and an
enrichment summary section:
## Enrichment Summary
_Last enrichment: <date> via GitNexus (index: <commit hash>)_
| Phase | Items Processed | Key Findings |
|-------|----------------|--------------|
| Danger zones | N entries | N upgraded to CRITICAL/HIGH |
| Extension points | N patterns | N registrations found |
| Execution flows | N flows indexed | N multi-flow hotspots |
| Clustering | N domains compared | N mismatches found |
| Shallow modules | N modules enriched | N confidence bumps |
7.2 Timestamp Annotations
All enrichment edits include a timestamp annotation:
(enriched <date> via GitNexus)
This allows /ctx-architecture on subsequent runs to distinguish
manual analysis from enrichment data.
7.3 Print Summary
Print a concise summary to the terminal:
Enrichment complete:
- Danger zones: N entries, N with blast radius data
- Extension points: N patterns, N total registrations
- Execution flows: N indexed, N multi-flow hotspots
- Clustering: N domains compared, N mismatches
- Shallow modules: N enriched, N confidence bumps
- Artifacts updated: DANGER-ZONES.md, EXTENSION-POINTS.md,
CHEAT-SHEETS.md, CONVERGENCE-REPORT.md, map-tracking.json
Deliverables
All changes are in-place edits to existing .context/ files
plus these standalone files:
| File | Created by | Updated by enrichment |
|---|
DANGER-ZONES.md | /ctx-architecture (principal) | Blast radius, risk levels |
EXTENSION-POINTS.md | This skill | Registration inventory |
CONVERGENCE-REPORT.md | /ctx-architecture | Updated scores, enrichment summary |
CHEAT-SHEETS.md | /ctx-architecture | Execution flow index |
ARCHITECTURE-PRINCIPAL.md | /ctx-architecture (principal) | Clustering comparison |
DETAILED_DESIGN.md | /ctx-architecture | Shallow module updates |
map-tracking.json | /ctx-architecture | Confidence bumps, enriched_at |
No new files are created beyond EXTENSION-POINTS.md (which only
this skill produces).
Design Constraints
- Sequential phases: each phase MUST complete before the next
begins. Do not interleave phases - complete one, write its
results, then move to the next.
- Idempotent: running enrichment twice updates existing
annotations, does not duplicate them. Before adding enrichment
data, remove or update prior
(enriched <date>) entries for
the same symbol. Timestamp annotations make previous enrichment
data identifiable.
- Incremental: each phase is independent. If one phase fails
(e.g., no danger zones exist), skip it and continue.
- Composable: can chain with
/ctx-architecture --principal
for a full "analyze + enrich" pipeline across sessions.
- Tool-aware: auto-detects available tools. GitNexus is
required; Gemini is optional (used for upstream pattern lookups
when comparing clustering or researching extension patterns).
Quality Checklist
After running, verify: