Skip to content

Commit a8df03c

Browse files
josealekhinejosealekhine
committed
deep dive.
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
1 parent 60ca30f commit a8df03c

15 files changed

Lines changed: 4451 additions & 143 deletions

File tree

‎docs/recipes/architecture-deep-dive.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
# / ctx: https://ctx.ist
3+
# ,'`./ do you remember?
4+
# `.,'\
5+
# \ Copyright 2026-present Context contributors.
6+
# SPDX-License-Identifier: Apache-2.0
7+
8+
title: Architecture Deep Dive
9+
icon: lucide/layers
10+
---
11+
12+
## The Problem
13+
14+
Understanding a codebase at the surface level is easy. Understanding
15+
where it will break under real-world conditions takes three passes:
16+
mapping what exists, quantifying how it connects, and hunting for
17+
where it silently fails. Most teams stop at the first pass.
18+
19+
## TL;DR
20+
21+
```bash
22+
# Pass 1: Map the system
23+
/ctx-architecture
24+
25+
# Pass 2: Enrich with code intelligence
26+
/ctx-architecture-enrich
27+
28+
# Pass 3: Hunt for failure modes
29+
/ctx-architecture-failure-analysis
30+
```
31+
32+
Each pass builds on the previous one. Run them in order. The
33+
output accumulates in `.context/` — each pass reads the prior
34+
artifacts and extends them.
35+
36+
## Commands and Skills Used
37+
38+
| Tool | Type | Purpose |
39+
|-----------------------------------------|-------|--------------------------------------------------|
40+
| `/ctx-architecture` | Skill | Map modules, dependencies, data flow, patterns |
41+
| `/ctx-architecture-enrich` | Skill | Verify blast radius and flows with code intel |
42+
| `/ctx-architecture-failure-analysis` | Skill | Generate falsifiable incident hypotheses |
43+
| `ctx deps` | CLI | Bootstrap dependency graph for Pass 1 |
44+
| `ctx status` | CLI | Quick structural overview |
45+
46+
## The Workflow
47+
48+
### Pass 1: Map what exists
49+
50+
```text
51+
/ctx-architecture
52+
```
53+
54+
Produces:
55+
56+
- **ARCHITECTURE.md** — succinct project map (< 4000 tokens),
57+
loaded at every session start
58+
- **DETAILED_DESIGN*.md** — deep per-module reference with
59+
exported API, data flow, danger zones, extension points
60+
- **CHEAT-SHEETS.md** — lifecycle flow diagrams
61+
- **map-tracking.json** — coverage state with confidence scores
62+
63+
This pass forces deep code reading. No shortcuts, no code
64+
intelligence tools — the agent reads every module it analyzes.
65+
That forced reading is what makes the subsequent passes useful.
66+
67+
**When to run**: First time on a codebase, or after significant
68+
structural changes (new packages, moved files, changed
69+
dependencies).
70+
71+
**Principal mode**: Add `principal` to get strategic analysis
72+
(ARCHITECTURE-PRINCIPAL.md, DANGER-ZONES.md from P4):
73+
74+
```text
75+
/ctx-architecture principal
76+
```
77+
78+
### Pass 2: Enrich with code intelligence
79+
80+
```text
81+
/ctx-architecture-enrich
82+
```
83+
84+
Takes the Pass 1 artifacts as baseline and layers on verified,
85+
graph-backed data from GitNexus:
86+
87+
- Blast radius numbers for key functions
88+
- Execution flow traces through hot paths
89+
- Domain clustering validation
90+
- Registration site discovery
91+
92+
This pass does not replace reading — it quantifies what reading
93+
found. If Pass 1 says "module X depends on module Y," Pass 2
94+
says "module X has 47 callers in module Y, and changing function
95+
Z would affect 12 downstream consumers."
96+
97+
**When to run**: After Pass 1, when you need quantified
98+
confidence for refactoring decisions or risk assessment.
99+
100+
**Requires**: GitNexus MCP server connected.
101+
102+
### Pass 3: Hunt for failure modes
103+
104+
```text
105+
/ctx-architecture-failure-analysis
106+
```
107+
108+
The adversarial pass. Reads all prior artifacts, then
109+
systematically hunts for correctness bugs across 9 failure
110+
categories:
111+
112+
1. Concurrency (races, deadlocks, goroutine leaks)
113+
2. Ordering assumptions (init, registration, shutdown)
114+
3. Cache staleness (TTL-less, read-your-writes, cross-process)
115+
4. Fan-out amplification (N+1, retry storms)
116+
5. Ownership and lifecycle (orphans, double-close)
117+
6. Error handling (silent swallowing, partial failure)
118+
7. Scaling cliffs (quadratic, unbounded, global locks)
119+
8. Idempotency failures (duplicate processing, retry mutations)
120+
9. State machine drift (illegal states, unvalidated transitions)
121+
122+
Every finding must meet an evidence standard: code path, trigger,
123+
failure path, silence reason, and code evidence. A mandatory
124+
challenge phase attempts to disprove each finding before it is
125+
accepted. Findings carry a confidence level (High/Medium/Low) and
126+
explicit risk score.
127+
128+
Produces **DANGER-ZONES.md** — a ranked inventory of findings
129+
split into Critical and Elevated tiers.
130+
131+
**When to run**: Before releases, after major refactors, when
132+
investigating incident categories, or when onboarding.
133+
134+
## What You Get
135+
136+
After all three passes, `.context/` contains:
137+
138+
| File | From | Purpose |
139+
|------|------|---------|
140+
| `ARCHITECTURE.md` | Pass 1 | System map (session-start context) |
141+
| `DETAILED_DESIGN*.md` | Pass 1 | Module-level deep reference |
142+
| `CHEAT-SHEETS.md` | Pass 1 | Lifecycle flow diagrams |
143+
| `map-tracking.json` | Pass 1 | Coverage and confidence data |
144+
| `CONVERGENCE-REPORT.md` | Pass 1 | What's covered, what's not |
145+
| `DANGER-ZONES.md` | Pass 3 | Ranked failure hypotheses |
146+
147+
Pass 2 enriches Pass 1 artifacts in-place rather than creating
148+
new files.
149+
150+
## Tips
151+
152+
- **Run Pass 1 with focus areas** if the codebase is large.
153+
The skill asks what to go deep on — name the modules you're
154+
about to change.
155+
- **You don't need all three passes every time.** Pass 1 is
156+
the foundation. Pass 2 and 3 are for when you need
157+
quantified confidence or adversarial rigor.
158+
- **Re-run Pass 1 incrementally.** It tracks coverage in
159+
`map-tracking.json` and only re-analyzes stale modules.
160+
- **Pass 3 is most valuable before releases.** The ranked
161+
DANGER-ZONES.md is a pre-release checklist.
162+
- **The trilogy maps to a question progression**: How does it
163+
work? How well does it connect? Where will it break?
164+
165+
## See Also
166+
167+
*See also: [Detecting and Fixing Context Drift](context-health.md)
168+
— keep architecture artifacts fresh between deep-dive sessions.*
169+
170+
*See also: [Dependency Graph](dependency-graph.md) — quick
171+
dependency overview without the full architecture pass.*

‎docs/recipes/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -363,6 +363,18 @@ file overlap, work in parallel, merge back.
363363

364364
---
365365

366+
### [Architecture Deep Dive](architecture-deep-dive.md)
367+
368+
Three-pass pipeline for understanding a codebase: **map** what
369+
exists, **enrich** with code intelligence, then **hunt** for
370+
where it will silently fail. Produces architecture docs,
371+
quantified dependency data, and ranked failure hypotheses.
372+
373+
**Uses**: `/ctx-architecture`, `/ctx-architecture-enrich`,
374+
`/ctx-architecture-failure-analysis`
375+
376+
---
377+
366378
### [Generating Dependency Graphs](dependency-graph.md)
367379

368380
Map your project's internal and external **dependency structure**.

0 commit comments

Comments
 (0)