Skill v1.0.1

version: "1.0.1" 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 the repo's own indexing entry point if it has one — a make gitnexus-index target, a script, or its GITNEXUS.md — else 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 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.)

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):

1. Run impact analysis on the named symbol:

`` mcp__gitnexus__impact({target: "<symbol>", direction: "upstream"}) ``

1. 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

1. 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 ``

1. Update DANGER-ZONES.md with enrichment data:

```markdown

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:

1. Query the call graph for registration patterns:

`` mcp__gitnexus__context({name: "<registration function>"}) ``

1. Build a registration inventory:

• All call sites with file:line references
• Count of registrations per pattern
• Any unregistered implementations (defined but never wired)

1. Write or update `.context/EXTENSION-POINTS.md`:

```markdown # Extension Points

_Generated <date>. Enriched via GitNexus call graph analysis._

## Summary

## 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

1. Read all processes from GitNexus:

`` READ gitnexus://repo/<name>/processes ``

1. 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.

1. Identify multi-flow hotspots - symbols that appear

in 3+ execution flows are integration points worth knowing

1. Update CHEAT-SHEETS.md with an execution flow index:

```markdown ## Execution Flow Index (via GitNexus)

_Enriched <date>. These flows are auto-detected from the call graph and complement the manually written cheat sheets above._

### Multi-Flow Hotspots

Symbols participating in 3+ flows (high-impact modification points):

```

Phase 5: Domain Clustering Comparison

1. Read auto-detected clusters from GitNexus:

`` READ gitnexus://repo/<name>/clusters ``

1. Read manual domain splits from DETAILED_DESIGN.md (the

domain file index if split, or section headers if monolithic)

1. 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

1. Write comparison to ARCHITECTURE-PRINCIPAL.md (if it exists)

or print to terminal: ```markdown ## Domain Clustering Comparison (enriched <date>)

### 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:

1. Run semantic queries for the module's key concepts:

`` mcp__gitnexus__query({query: "<module purpose or key concept>"}) ``

1. Get context on key symbols:

`` mcp__gitnexus__context({name: "<key exported symbol>"}) ``

1. Read process participation - which execution flows does

this module participate in?

1. Update the module's DETAILED_DESIGN.md section with

findings - callers, execution flow participation, cross-module relationships that reading alone may have missed

1. Update confidence score in map-tracking.json with

justification: ``json "<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:

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