C3 Query - Architecture Navigation

Navigate C3 docs AND explore corresponding code. Full context = docs + code.

REQUIRED: Load References

Before proceeding, use Glob to find and Read these files:

1. **/references/skill-harness.md - Red flags and complexity rules
2. **/references/layer-navigation.md - How to traverse C3 docs

Query Flow

Query → Clarify Intent → Navigate Layers → Extract References → Explore Code
              │
              └── Use AskUserQuestion if ambiguous

Progress Checklist

Query Progress:
- [ ] Step 0: Intent clarified (or skipped if specific)
- [ ] Step 1: Context navigated (found relevant container)
- [ ] Step 2: References extracted (code paths, symbols)
- [ ] Step 3: Code explored (verified against docs)
- [ ] Response delivered with layer, refs, insights

---

Step 0: Clarify Intent

Ask when:

• Query vague ("how does X work?" - which aspect?)
• Multiple interpretations ("authentication" - login? tokens? sessions?)
• Scope unclear ("frontend" - whole container or specific component?)

Skip when:

• Query includes C3 ID (c3-102)
• Query specific ("where is login form submitted?")
• User says "show me everything about X"

---

Step 1-2: Navigate and Extract

Follow layer navigation: Context → Container → Component

Doc Section	Extract For Code
Component name	Class/module names
## References	Direct file paths, symbols
Technology	Framework patterns
Entry points	Main files, handlers

Reference Lookup

If query relates to patterns/conventions:

1. Check .c3/refs/ for ref-* matching topic
2. Return ref content + citing components

---

Step 3: Explore Code

Use extracted references:

• Glob: src/auth/**/*.ts
• Grep: Class names, functions
• Read: Specific files from ## References

---

Query Types

Type	User Says	Response
Docs	"where is X", "explain X"	Docs + suggest code exploration
Code	"show me code for X"	Full flow through code
Deep	"explore X thoroughly"	Docs + Code + Related
Constraints	"what rules/constraints apply to X"	Full constraint chain

---

Constraint Chain Query

When user asks about rules, constraints, or boundaries for a layer:

Flow

Identify Layer → Read Upward Chain → Collect Cited Refs → Synthesize Chain

Steps

1. Identify target layer from query (c3-NNN, c3-N, or c3-0)

2. Read upward through hierarchy:

   • If component: read component → container → context
   • If container: read container → context
   • If context: read context only

3. At each level, extract:

   • Explicit constraints ("components MUST...", "MUST NOT...")
   • Implicit boundaries (what the layer is responsible for)
   • Layer-specific rules

4. Collect cited refs:

   • From component's Related Refs section
   • From container's pattern references
   • From context's system-wide patterns

5. Read each cited ref and extract key rules

Response Format

**Constraint Chain for c3-NNN (Component Name)**

**Context Constraints (c3-0):**
- [System-wide rule 1]
- [System-wide rule 2]

**Container Constraints (c3-N):**
- [Container boundary 1]
- [Coordination rule]

**Cited Pattern Constraints:**
- **ref-X:** [Key rules from this pattern]
- **ref-Y:** [Key rules from this pattern]

**Layer Boundaries:**
This component MAY:
- [Permitted responsibilities]

This component MUST NOT:
- [Prohibited actions - from higher layers]

**Visualization:**
[Mermaid diagram showing constraint inheritance]

Example

User: "What constraints apply to c3-201?"

1. Read c3-201-auth-middleware.md → cites ref-error-handling, ref-auth
2. Read c3-2-api/README.md → "Middleware must be stateless"
3. Read .c3/README.md → "All auth uses RS256"
4. Read ref-error-handling.md → "Use correlation IDs"
5. Read ref-auth.md → "Tokens expire in 24h"

Response:
**Constraint Chain for c3-201 (Auth Middleware)**

**Context Constraints (c3-0):**
- All authentication must use RS256 signing

**Container Constraints (c3-2-api):**
- Middleware must be stateless
- Request context via headers, not shared state

**Cited Pattern Constraints:**
- **ref-error-handling:** Use correlation IDs in all error responses
- **ref-auth:** Token expiry 24h, refresh via /auth/refresh

**Layer Boundaries:**
This component MAY:
- Validate JWT tokens
- Reject unauthorized requests
- Set request context for downstream handlers

This component MUST NOT:
- Store session state (container: stateless middleware)
- Define new auth schemes (context: RS256 only)
- Handle business logic errors (use ref-error-handling pattern)

Edge Cases

Situation	Action
Topic not in C3 docs	Search code directly, suggest documenting if significant
Spans multiple containers	List all affected containers, explain relationships
Docs seem stale	Note discrepancy, suggest /c3 audit or /alter to fix

---

Examples

Example 1: Component lookup

User: "Where is authentication handled?"

Step 1: Read .c3/README.md → Find c3-2-api container handles auth
Step 2: Read .c3/c3-2-api/README.md → Find c3-201-auth-middleware
Step 3: Read .c3/c3-2-api/c3-201-auth-middleware.md → Get code refs

Response:
**Layer:** c3-201 (Auth Middleware)

Authentication is handled by the AuthMiddleware component in the API container.

**Code References:**
- `src/api/middleware/auth.ts` - JWT validation
- `src/api/middleware/session.ts` - Session management

**Key Insights:**
Uses RS256 for JWT signing. Sessions stored in Redis.

**Related:** See c3-202-user-service for user lookup

Example 2: Pattern lookup

User: "How does error handling work?"

Step 1: Read .c3/README.md → Multiple containers
Step 2: Check .c3/refs/ → Find ref-error-handling.md

Response:
**Pattern:** ref-error-handling

Error handling follows a centralized pattern documented in refs.

**Pattern Summary:**
- All errors extend BaseError class
- HTTP errors map to status codes via errorToStatus()
- Logged with correlation ID

**Used By:** c3-201, c3-203, c3-205

---

Response Format

**Layer:** <c3-id> (<name>)

<Architecture from docs>

**Code References:**
- `path/file.ts` - <role>

**Key Insights:**
<Observations from code>

**Related:** <navigation hints>