C3 Ref - Pattern Management

Cross-cutting patterns (refs) are authoritative constraints. They define how things should be done system-wide. This skill makes refs first-class citizens with proper workflows.

CRITICAL: Component Categorization

Load **/references/component-categories.md for the full Foundation vs Feature vs Ref rules.

Key rule for refs: Refs have NO ## Code References section. If it needs one, it's a component.

REQUIRED: Load References

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

1. **/references/skill-harness.md - Red flags and complexity rules
2. **/templates/ref.md - Ref template structure

Mode Selection

Mode: Add

Create a new ref from discovered or proposed pattern.

Flow

Describe Pattern → Discover Usage → Generate Ref → Update Citings → Create ADR

Steps

Step 1: Clarify Pattern

Use AskUserQuestion to understand:

AskUserQuestion:
  question: "What pattern do you want to document?"
  options:
    - "Error handling convention"
    - "Data fetching pattern"
    - "Authentication approach"
    - "Something else (describe)"

Get:

• Pattern name (slug: ref-{slug})
• Pattern goal (what it standardizes)
• Key rules (what must be followed)

Step 2: Discover Existing Usage

Search codebase for pattern indicators:

# Example for error handling
rg "extends.*Error|throw new|catch\s*\(" --type ts

# Example for retry pattern
rg "retry|backoff|exponential" --type ts

Identify:

• Files/components already using this pattern
• Variations in how it's implemented
• Common vs divergent approaches

Step 3: Generate Ref

Create .c3/refs/ref-{slug}.md from template:

---
id: ref-{slug}
title: {Pattern Title}
goal: {What this pattern standardizes}
---

# {Pattern Title}

## Goal

{Why this pattern exists - what inconsistency it prevents}

## Pattern

{Core rules that MUST be followed}

### Required Elements

- {Element 1}
- {Element 2}

### Examples

**Correct:**
\`\`\`typescript
{good example}
\`\`\`

**Incorrect:**
\`\`\`typescript
{bad example}
\`\`\`

## Cited By

<!-- Updated automatically when components cite this ref -->
- c3-{N}{NN} ({component name})

Step 4: Update Citing Components

For each component that uses this pattern:

1. Read component doc
2. Add ref to ## Related Refs table
3. Remove any duplicated pattern content (cite instead)

Step 5: Create Adoption ADR

Create mini-ADR at .c3/adr/adr-YYYYMMDD-ref-{slug}-adoption.md:

---
id: adr-YYYYMMDD-ref-{slug}-adoption
title: Adopt {Pattern Title} as standard
status: implemented
---

# Adopt {Pattern Title} as Standard

## Problem

{Pattern was implemented inconsistently across N components}

## Decision

Document pattern as ref-{slug}. All existing usages now cite this ref.

## Affected Layers

| Layer | Change |
|-------|--------|
| refs | Added ref-{slug} |
| components | {list of updated components} |

Mode: Update

Modify an existing ref with impact analysis.

Flow

Identify Change → Find Citings → Check Compliance → Surface Violations → Execute

Steps

Step 1: Clarify Change

AskUserQuestion:
  question: "What change do you want to make to ref-{slug}?"
  options:
    - "Add a new rule"
    - "Modify an existing rule"
    - "Remove a rule"
    - "Clarify/improve documentation"

Step 2: Find All Citings

# Find components citing this ref
rg "ref-{slug}" .c3/c3-*/c3-*.md

List all citing components.

Step 3: Check Compliance

For each citing component:

• Read code references from component doc
• Check if code still complies with proposed change
• Categorize: compliant / needs-update / breaking

Step 4: Surface Impact

AskUserQuestion:
  question: "This change affects N components. M are already compliant, K need updates."
  options:
    - "Proceed - update ref and K components"
    - "Narrow the change - only affect compliant ones"
    - "Cancel - too much impact"

Step 5: Execute

If proceeding:

1. Update ref document
2. Create ADR for ref change
3. For non-compliant components: either update or note as TODO in ADR

## Affected Components

| Component | Status | Action |
|-----------|--------|--------|
| c3-101 | compliant | None |
| c3-103 | needs-update | Updated code in PR #123 |
| c3-205 | breaking | TODO: refactor in follow-up |

Step 6: Route to c3-alter if Code Changes Required

If pattern change requires code modifications in components:

"Pattern update requires code changes in {N} components. Route to /alter to create an ADR for implementation."

All code changes MUST go through c3-alter to maintain the ADR-first principle. Do not edit component code directly from c3-ref.

Mode: List

Show all refs in the system.

Flow

ls .c3/refs/ref-*.md

For each, read and extract:

• id
• title
• goal
• Count of citings

Response Format

**C3 Patterns (Refs)**

| Ref | Title | Goal | Cited By |
|-----|-------|------|----------|
| ref-error-handling | Error Handling | Consistent error responses | 5 components |
| ref-auth | Authentication | Token-based auth | 3 components |

Mode: Usage

Show where a specific ref is used.

Flow

# Find citings
rg "ref-{slug}" .c3/c3-*/c3-*.md

# Read each citing component

Response Format

**ref-{slug} Usage**

**Cited by:**
- c3-101 (Auth Middleware) - JWT validation
- c3-103 (User Service) - Login flow
- c3-205 (API Gateway) - Request auth

**Pattern Summary:**
{Key rules from the ref}

Anti-Patterns

Examples

Example 1: Add Pattern

User: "We use a retry pattern across all API calls. Document it."

Step 1: Pattern = retry with exponential backoff
Step 2: rg "retry|backoff" → found in c3-101, c3-103, c3-205
Step 3: Create .c3/refs/ref-retry-pattern.md
Step 4: Update 3 component docs with Related Refs
Step 5: Create adr-20260120-ref-retry-pattern-adoption.md

Response:
Created ref-retry-pattern. Updated 3 components:
- c3-101 (HTTP Client)
- c3-103 (External API)
- c3-205 (Webhook Handler)

Example 2: Update Pattern

User: "Add jitter to the retry pattern"

Step 1: Change = add jitter requirement
Step 2: Citings: c3-101, c3-103, c3-205
Step 3: Check code:
  - c3-101: already uses jitter ✓
  - c3-103: no jitter, needs update
  - c3-205: no jitter, needs update
Step 4: "2 components need updates. Proceed?"
Step 5: User: "Yes"
  - Update ref-retry-pattern.md
  - Create ADR with TODO for c3-103, c3-205