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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
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 the repo's own indexing entry point if
it has one — a make gitnexus-index target, a script, or its
— else ; equivalents
apply their own indexing step) and architecture artifacts already
exist
GITNEXUS.md
gitnexus analyze --embeddings
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
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 index the repo with
its own entry point if it has one (a `make gitnexus-index` target,
a script, or its GITNEXUS.md), else run:
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.
Reindex with the repo's own entry point (a `make gitnexus-index`
target, a script, or its GITNEXUS.md) if it has one, else run
`gitnexus analyze`; then re-run this skill.
(For non-GitNexus code-intelligence MCPs, apply the same
staleness check using whatever the underlying tool exposes.)
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>** - <originaldescription> - Blast radius: d=1: N, d=2: N, d=3: N
- Affected flows: <listofprocessnames> - Risk: HIGH (enriched 2026-03-25 via GitNexus)
- Modification advice: <updatedbasedonblastradius>
Update the summary table with verified risk levels.
Phase 3: Extension Point Enrichment
For each extension point identified in DETAILED_DESIGN.md module
sections:
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: <commithash>)_
| 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:
Preflight confirmed GitNexus connected and index fresh
Required architecture artifacts were read before enrichment
Danger zones enriched with blast radius (d=1/d=2/d=3 counts)
Risk levels assigned using verified criteria (not guessed)
Extension points have file:line references (not just names)
Execution flow index added to CHEAT-SHEETS.md
Cross-community hotspots identified (symbols in 3+ flows)
Domain clustering compared (mismatches surfaced)
Shallow modules enriched only if understanding improved
Confidence bumps justified (not inflated by raw counts)
All edits include timestamp annotations
CONVERGENCE-REPORT.md regenerated from map-tracking.json
Enrichment summary printed to terminal
DANGER-ZONES.md summary table updated with verified risk
EXTENSION-POINTS.md written (if extension points exist)
map-tracking.json updated with enriched_at timestamps