activememory/ctx/ctx-architecture-enrich

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