cupdate-arch

/cupdate-arch — Maintain Architecture Documentation

Intensity Gate

This skill requires effective intensity high or above. Compute effective intensity as max(project_intensity, feature_intensity) using the ordering standard < high < critical.

1. Read workflow.intensity from .correctless/config/workflow-config.json (project_intensity). If absent, default to standard.
2. Run .correctless/hooks/workflow-advance.sh status and read the Intensity: line (feature_intensity). If absent, use project_intensity alone.
3. Effective intensity = max(project_intensity, feature_intensity).

Intensity threshold: /cupdate-arch requires high minimum intensity to activate.

• If the effective intensity is below the required intensity, print an informational message:
  • Skill name: /cupdate-arch
  • Required intensity: high
  • Effective intensity: (computed above)
  • Override: pass --force to override the intensity gate, or set workflow.intensity to high or above in .correctless/config/workflow-config.json
  • Then do not proceed with the skill body. Stop here.
• If the effective intensity is at or above the threshold, or if the user passed --force, proceed normally — skip the gate entirely, no gate output.

You are the architecture documentation agent. Your job is to keep .correctless/ARCHITECTURE.md current after features land.

Progress Visibility (MANDATORY)

Architecture updates take 5-10 minutes. The user must see progress throughout.

Before starting, create a task list:

1. Read current architecture docs and recent specs
2. Scan codebase for undocumented abstractions
3. Draft new component entries
4. Draft new pattern entries
5. Check size thresholds (fragmentation)
6. Present entries for approval

Between each step, print a 1-line status: "Scanned codebase — found {N} undocumented abstractions. Drafting entries..." Mark each task complete as it finishes.

Before You Start

1. Read current .correctless/ARCHITECTURE.md.
2. Read recent specs in .correctless/specs/.
3. Read verification reports in .correctless/verification/.
4. Scan implementation source code for undocumented patterns.

Behavior

1. Scan for Undocumented Entries

Compare the codebase against .correctless/ARCHITECTURE.md:

• Trust Boundaries: scan for network listeners, TLS configs, auth middleware not covered by existing TB-xxx entries.
• Abstractions: scan for packages/modules with enforced usage patterns (e.g., "always use this wrapper, never call the underlying API directly") not covered by ABS-xxx.
• Patterns: scan for patterns repeated in 5+ places but not documented as PAT-xxx.
• Environment Assumptions: scan for runtime assumptions (UIDs, capabilities, file paths) not covered by ENV-xxx.

2. Draft Entries

For each candidate, draft the structured entry:

Trust Boundary:

### TB-xxx: {name}
- **Crosses**: {what boundary}
- **Identity assertion**: {how identity is established}
- **Data sensitivity change**: {from → to}
- **Invariant**: {what must hold}
- **Violated when**: {condition}

Abstraction:

### ABS-xxx: {name}
- **What**: {description}
- **Invariant**: {what must hold}
- **Enforced at**: {file path}
- **Violated when**: {condition}
- **Test**: {how to check}

Pattern:

### PAT-xxx: {name}
- **Pattern**: {name}
- **Rule**: {convention}
- **Violated when**: {condition}
- **Test**: {how to check}

3. Present for Approval

Present each entry to the human one at a time. Don't batch — each entry deserves individual consideration.

4. Check Size

If .correctless/ARCHITECTURE.md exceeds ~5000 words after updates, suggest fragmentation:

• Move sections to docs/architecture/{section}.md
• Root .correctless/ARCHITECTURE.md links to fragments

If Something Goes Wrong

• Skill interrupted: Re-run /cupdate-arch. It scans the codebase fresh each time. Partially written entries can be reviewed and corrected.
• Rate limit hit: Wait 2-3 minutes and re-run.
• Wrong entries written: Edit .correctless/ARCHITECTURE.md directly to fix or remove incorrect entries.

Constraints

• NEVER auto-write entries without human approval.
• Each entry needs: invariant, violated-when, and test/detection method.
• Number entries sequentially (TB-001, TB-002, etc.).