c3-query

C3 Query - Architecture Navigation

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

Relationship to c3-navigator agent: This skill defines the query workflow. The c3-skill:c3-navigator agent implements this workflow with sub-agent dispatch for token efficiency. Use the agent when spawning via Task tool; use this skill directly for inline execution.

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)

1. Read upward through hierarchy:
2. If component: read component → container → context
3. If container: read container → context
4. If context: read context only

1. At each level, extract:
2. Explicit constraints ("components MUST...", "MUST NOT...")
3. Implicit boundaries (what the layer is responsible for)
4. Layer-specific rules

1. Collect cited refs:
2. From component's Related Refs section
3. From container's pattern references
4. From context's system-wide patterns

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