C3 Component Level Exploration

⛔ CRITICAL GATE: Load Parent Container + Context First

STOP - Before ANY component-level work, execute:

# Load grandparent Context
cat .c3/README.md 2>/dev/null || echo "NO_CONTEXT"

# Load parent Container (REQUIRED - components inherit from here)
cat .c3/c3-{N}-*/README.md 2>/dev/null || echo "NO_CONTAINER"

# Check if component is listed in Container
grep "c3-{N}{NN}" .c3/c3-{N}-*/README.md 2>/dev/null || echo "COMPONENT_NOT_IN_CONTAINER"

# Load existing component doc (if exists)
cat .c3/c3-{N}-*/c3-{N}{NN}-*.md 2>/dev/null || echo "NO_COMPONENT_DOC"

Based on output:

If "NO_CONTAINER" → STOP. Container must exist first. Escalate to c3-container-design.
If "COMPONENT_NOT_IN_CONTAINER" → STOP. Add component to Container first.
If component doc exists → Read it completely before proposing changes

⚠️ DO NOT read ADRs unless user specifically asks:

Component work focuses on HOW, not historical WHY
ADRs add unnecessary context → hallucination risk
Only read: Context, parent Container, sibling Components (if dependencies)

Why this gate exists: Components INHERIT from Container (and transitively from Context). A component cannot exist without being listed in its parent Container.

Self-check before proceeding:

[ ] I executed the commands above
[ ] I read parent Container doc
[ ] This component IS listed in Container's component inventory
[ ] I know what contract/responsibility this component has (from Container)
[ ] I read existing component doc (if exists)

Overview

Component is the leaf layer - it inherits all constraints from above and implements actual behavior.

Position: LEAF (c3-{N}{NN}) | Parent: Container (c3-{N}) | Grandparent: Context (c3-0)

📁 File Location: Component is .c3/c3-{N}-{slug}/c3-{N}{NN}-{slug}.md - INSIDE the container folder.

Announce: "I'm using the c3-component-design skill to explore Component-level impact."

The Principle

Upper layer defines WHAT. Lower layer implements HOW.

At Component level:

Container defines WHAT I am (my existence, my responsibility)
I define HOW I implement that responsibility
Code implements my documentation (in the codebase, not in C3)
I do NOT invent my responsibility - that's Container's job

Integrity rules:

I must be listed in Container before I can exist
My "Contract" section must reference what Container says about me
If Container doesn't mention me, I don't exist as a C3 document

Include/Exclude

| Include (Component Level) | Exclude (Push Up) | |---------------------------|-------------------| | Interface (IN → OUT) | WHAT component does (Container) | | Internal organization | Component relationships (Container) | | Conventions & rules | WHY patterns chosen (Container/ADR) | | Edge cases & errors | Code snippets | | | File paths |

Litmus test: "Is this about HOW this component implements its contract?"

Diagram-First Principle

Components are documented visually. The diagram tells the story, text supports it.

Every component explains:

Its boundary - what it's responsible for (and what it's not)
Hand-off points - where information exchanges happen with other components
Internal processing - what happens inside (self-contained)

Interface Diagram (Required)

Shows the boundary and hand-offs:

flowchart LR
    subgraph IN["Receives"]
        I1[From Component A]
        I2[From External]
    end

    subgraph SELF["Owns"]
        S1[Processing]
        S2[Transformation]
    end

    subgraph OUT["Provides"]
        O1[To Component B]
        O2[To Caller]
    end

    IN --> SELF --> OUT

Additional Diagrams (Where Applicable)

Use multiple diagrams when needed - just enough to explain:

| Diagram Type | Use When | |--------------|----------| | Sequence | Hand-off between multiple components matters | | State | Component has lifecycle/state transitions | | Organization | Internal structure is complex (layers, subsystems) |

Foundation vs Business components:

Foundation (e.g., Hono): Shows the transition point - where framework ends and business begins. What it provides TO business components.
Business (e.g., User Handler): Shows the flow - receives from foundation, processes, hands off results.

⛔ NO CODE ENFORCEMENT (MANDATORY)

Component docs describe HOW things work, NOT the actual implementation.

What Counts as Code (PROHIBITED)

| Prohibited | Example | Write Instead | |------------|---------|---------------| | Implementation code | function handle() {...} | Flow diagram | | Type definitions | interface User {...} | Table: Field | Type | Purpose | | Config snippets | { "port": 3000 } | Table of settings | | SQL/queries | SELECT * FROM... | Access pattern description | | JSON/YAML schemas | { "eventId": "uuid" } | Table with dot notation | | Example payloads | Request/response JSON | Table: Field | Type | Example |

Why Mermaid is Allowed but JSON is Not

Mermaid = visual flow/state diagrams (architectural)
JSON/YAML = data structure syntax (implementation)
Rule: If it could be parsed by JSON/YAML parser → use table instead

Exploration Process

Phase 1: Verify Integrity

From loaded Container, extract:

Component's responsibility (from Container's component table)
Related components (siblings)
Technology constraints
Pattern constraints

If component not in Container: STOP. Escalate to c3-container-design.

Phase 2: Analyze Change Impact

| Check | If Yes | |-------|--------| | Breaks interface/patterns? | Escalate to c3-container-design | | Needs new tech? | Escalate to c3-container-design | | Affects siblings? | Coordinate (may need Container update) | | Implementation only? | Proceed |

Phase 3: Socratic Discovery

By container archetype:

Service: Processing steps? Dependencies? Error paths?
Data: Structure? Queries? Migrations?
Boundary: External API? Mapping? Failures?
Platform: Process? Triggers? Recovery?

Template

See component-template.md for complete structure with frontmatter, diagrams, and examples.

Required sections:

Contract (from parent Container)
Interface (diagram showing boundary - REQUIRED)
Hand-offs table
Conventions table
Edge Cases & Errors table

Optional sections (include based on component nature):

Additional diagrams (Sequence, State, Organization)
Configuration, Dependencies, Invariants, Performance

Keep it lean: Simple component = 5 sections. Complex framework = multiple diagrams + optional sections.

⛔ Enforcement Harnesses

Harness 1: No Code

Rule: No code blocks except Mermaid diagrams.

# Check for non-mermaid code blocks
grep -E '```[a-z]+' .c3/c3-{N}-*/c3-{N}{NN}-*.md | grep -v mermaid
# Should return nothing

🚩 Red Flags:

function, class, interface, type keywords
import, require, export statements
File extensions like .ts, .js, .py
JSON/YAML blocks (even for "schemas")
"Example payload" in code blocks

Harness 2: Diagram-First

Rule: Interface diagram (IN → Processing → OUT) is REQUIRED.

Required sections:

Frontmatter (id, c3-version, title, type, parent, summary)
Contract (from parent Container)
Interface (Mermaid diagram REQUIRED - boundary and hand-offs)
Hand-offs (table - what exchanges with whom)
Conventions (table of rules)
Edge Cases & Errors (table)

Optional sections (include based on component nature):

Additional diagrams (Sequence, State, Organization) - where needed
Configuration - significant config surface
Dependencies - external dependencies matter
Invariants - key guarantees to verify
Performance - throughput/latency matters

🚩 Red Flags:

Missing Interface diagram
No IN/OUT structure in diagram
Text-heavy without diagrams
Code blocks present

Verification Checklist

Before claiming completion, execute:

# Verify component doc exists in correct location
ls .c3/c3-{N}-*/c3-{N}{NN}-*.md

# Verify frontmatter
grep -E "^id:|^type:|^parent:" .c3/c3-{N}-*/c3-{N}{NN}-*.md

# Verify Interface diagram exists with IN/OUT structure
grep -c '```mermaid' .c3/c3-{N}-*/c3-{N}{NN}-*.md  # Should be >= 1
grep -E "subgraph.*(IN|OUT)" .c3/c3-{N}-*/c3-{N}{NN}-*.md  # Should find IN/OUT

# Verify NO non-mermaid code blocks
non_mermaid=$(grep -E '```[a-z]+' .c3/c3-{N}-*/c3-{N}{NN}-*.md | grep -v mermaid | wc -l)
echo "Non-mermaid code blocks: $non_mermaid (should be 0)"

[ ] Critical gate executed (Container + Context loaded)
[ ] Component IS listed in parent Container's inventory
[ ] "Contract" section references Container's description
[ ] Interface diagram present (boundary and hand-offs)
[ ] Hand-offs table present (what exchanges with whom)
[ ] Conventions table present (rules for consistency)
[ ] Edge Cases & Errors table present
[ ] NO code blocks (except Mermaid)
[ ] Additional diagrams justified - only if Sequence/State/Organization needed
[ ] Optional sections justified - only included if relevant to this component

📚 Reading Chain Output

At the end of component work, output a reading chain for related docs.

Format:

## 📚 To Go Deeper

This component (c3-NNN) is part of:

**Ancestors (understand constraints):**
└─ c3-0 (Context) → c3-N (Container) → c3-NNN (this)

**Sibling components (if dependencies):**
├─ c3-NMM - [why this sibling matters]
└─ c3-NKK - [dependency relationship]

**Parent container (for context):**
└─ c3-N-{slug} - [what contract this component fulfills]

*Reading chain generated from component's dependencies and parent.*

Rules:

List siblings only if this component depends on or affects them
Always include parent Container for contract reference
Include Context only if cross-cutting concerns are relevant
Never include ADRs unless user asked

When NOT to Use

Escalate to c3-container-design if:

Change affects component relationships (not just one component's internals)
New technology/pattern needed
Component not yet listed in parent Container

Escalate to c3-context-design if:

Cross-cutting concern (affects multiple containers)
New protocol or boundary needed

Wrong layer symptoms:

Describing WHAT component does → Container's job
Documenting WHY component exists → Container's job
Including cross-container flows → Context's job

Change Impact Decision

flowchart TD
    A[Analyze Change] --> B{Breaks interface<br/>or patterns?}
    B -->|yes| C[Escalate to<br/>c3-container-design]
    B -->|no| D{Needs new<br/>technology?}
    D -->|yes| C
    D -->|no| E[Document at<br/>Component level]

Common Rationalizations

| Excuse | Reality | |--------|---------| | "JSON is clearer than a table" | JSON is code. Use table with Field | Type | Example columns. | | "Just one example payload won't hurt" | Examples become implementation. Describe structure, don't show syntax. | | "Code is easier to understand" | Code is implementation. Component doc describes patterns, not implements. | | "Type definitions help readers" | Types are code. Use tables with Field, Type, Purpose columns. | | "I'll use a simple config snippet" | Config syntax is code. Table: Setting | Default | Purpose. | | "Mermaid is code too" | Mermaid is architectural diagram (allowed). JSON/YAML is data structure (prohibited). | | "Interface diagram not needed for simple component" | REQUIRED. Even simple components have IN → OUT boundary. |

Common Mistakes

| Mistake | Fix | |---------|-----| | Including code blocks | Use tables. Field | Type | Purpose for structures. | | Skipping Interface diagram | REQUIRED. Shows IN → Processing → OUT boundary. | | Not checking Container first | Component must be listed in parent Container inventory. | | Text-heavy docs | Lead with diagrams. Text supports visuals, not vice versa. | | Missing Hand-offs table | REQUIRED. Shows what exchanges with whom. | | Describing WHAT not HOW | WHAT is Container's job. Component explains HOW. |

references/core-principle.md - The C3 principle
defaults.md - Component layer rules
references/container-archetypes.md - How archetype shapes component docs
references/diagram-patterns.md - Diagram guidance