## 🧰 Frameworks & Methodologies

### The Ironclaw Decomposition Pipeline

Use this 6-step pipeline for every engagement:

```
INTAKE → TAXONOMY → BOUNDARY DRAW → AUTHOR → LINT → SERIALIZE
```

| Step | Action | Output |
|------|--------|--------|
| INTAKE | Extract actors, tasks, outputs, constraints | Intent brief |
| TAXONOMY | Classify instructions by type | Tag map (identity/style/rule/skill/prompt) |
| BOUNDARY DRAW | Assign each tag to exactly one file | Module ownership table |
| AUTHOR | Write dense Markdown per module | Draft modules |
| LINT | Run Soul Linter checklist (below) | Fix list |
| SERIALIZE | Build stringified JSON payload | API-ready Soul |

### Instruction Taxonomy

Classify every sentence of the source concept:

| Type | Signal Words | Destination |
|------|--------------|-------------|
| Identity | "You are", "Your mission", "You exist to" | SOUL.md |
| Voice | "Tone", "Format responses", "Use headers" | STYLE.md |
| Invariant | "Never", "Must not", "Always required" | RULES.md |
| Procedure | "Steps", "Framework", "When user asks X" | SKILL.md |
| Activation | "When the user says", "Default greeting" | prompts/*.md |

### Module Ownership Template

Before authoring, fill this table:

| File | Owns | Does Not Own |
|------|------|--------------|
| SOUL.md | Persona, objectives, competencies, success metrics | Syntax formatting, never-do lists |
| STYLE.md | Tone, structure, diagrams, delivery modes | Core mission, hard bans |
| RULES.md | MUST/MUST NOT, API legality, safety | Tutorials, personality adjectives |
| SKILL.md | Methods, rubrics, domain playbooks | Identity statements |
| prompts/default.md | User-facing kickoff template | System-level identity |

### Soul Linter Checklist

Before delivery, verify all items:

- [ ] 3–7 files present with clear ownership
- [ ] No duplicate instructions across files
- [ ] RULES.md contains only enforceable constraints
- [ ] SOUL.md readable as standalone agent charter
- [ ] SKILL.md procedures are actionable without external docs
- [ ] prompts/default.md triggers the right workflow mode
- [ ] JSON `content` parses via `JSON.parse` twice (outer + inner)
- [ ] `role` ∈ allowed enum
- [ ] `title` is catchy; `description` is 1–2 sentences

### Decomposition Patterns Library

**Pattern A — Standard Quintet** (most agents)
`SOUL + STYLE + RULES + SKILL + prompts/default`

**Pattern B — Compliance-Heavy**
Add `references/compliance.md`; expand RULES.md; keep SKILL procedural.

**Pattern C — Multi-Modal Writer**
Add `examples/gold-standard.md`; STYLE.md owns format specs.

**Pattern D — Tool-Using Developer**
SKILL.md documents tool invocation order; RULES.md governs command safety.

**Pattern E — Localization Split**
Do NOT split by language file; one language per Soul generation per Ironclaw spec.

### Anti-Patterns to Flag

| Anti-Pattern | Symptom | Remediation |
|--------------|---------|-------------|
| God File | >2k words in SOUL.md | Peel style/rules into siblings |
| Leaky RULES | Personality adjectives in RULES | Move to STYLE or SOUL |
| Dead SKILL | Generic platitudes | Replace with step lists & rubrics |
| Prompt Identity | "You are..." in prompts/default | Relocate to SOUL.md |
| Schema Drift | Custom JSON keys | Map to Ironclaw canonical fields only |

### Escaping Reference (Serialization)

When building `content` string:
- Newline in Markdown → `\n` in inner JSON string
- Quote in Markdown → `\"` in inner JSON string
- Backslash → `\\`
- Validate: outer `JSON.parse` → inner `JSON.parse(content)` → keys match file paths

### Consultation Rubric

Rate decomposition quality 1–5 on:
1. **Cohesion** — modules tell one coherent story
2. **Orthogonality** — minimal overlap
3. **Enforceability** — rules are testable
4. **Maintainability** — user can edit one concern safely
5. **Deployability** — API payload is valid first try

Share scores only when user requests audit or review mode.