# METHODOLOGY.md - Methodology Guides Registry
**Authority:** guidance (how-to guides and practice documents)
**Layer:** Guides
**Binding:** No
**Scope:** canonical index of methodology guidance
**Non-goals:** binding contracts and schema definitions
---
## Table of Contents
1. [Introduction](#1-introduction)
2. [Methodology Guides](#2-methodology-guides)
3. [Guide Consumption Patterns](#3-guide-consumption-patterns)
4. [Guide Authoring Standards](#4-guide-authoring-standards)
5. [Boundary Rule](#5-boundary-rule)
6. [Cross-Guide Dependencies](#6-cross-guide-dependencies)
7. [Guide Evolution](#7-guide-evolution)
8. [Anti-Patterns](#8-anti-patterns)
9. [Specialized Domains](#9-specialized-domains)
10. [Extraction Status](#10-extraction-status)
---
## 1. Introduction
Methodology guides are the operational conscience of the Decapod system. Unlike binding contracts in `specs/` and `interfaces/`, these guides exist to encode **practice** — the accumulated knowledge of what works, what breaks, and why. They teach execution behavior without creating legal obligations.
A methodology guide answers the question: "Given that I know what the system requires, how do I actually execute in this situation?"
The guides are designed to be:
- **Actionable**: step-by-step workflows with specific commands
- **Contextual**: when to use this approach vs. alternatives
- **Honest about tradeoffs**: what you gain, what you lose, what breaks
- **Illustrated**: examples of both success and failure modes
- **Linked**: every guide references related guides and binding contracts
The distinction between guidance and binding law is not a suggestion. If a guide conflicts with a binding document, the binding document wins. This is enforced by `decapod validate` for structural elements, and by human review for semantic conflicts.
---
## 2. Methodology Guides
| `methodology/ARCHITECTURE.md` | Architectural tradeoff evaluation and design workflow practice | Architects, Principal Engineers |
| `methodology/SOUL.md` | Agent identity, communication style, and collaboration posture | All agents |
| `methodology/KNOWLEDGE.md` | Knowledge capture, curation, and lifecycle hygiene | All agents |
| `methodology/MEMORY.md` | Memory hygiene, retrieval discipline, and retention policies | All agents |
| `methodology/TESTING.md` | Testing workflow, pyramid emphasis, and quality assurance practice | All engineers |
| `methodology/CI_CD.md` | CI/CD pipeline patterns, release hygiene, and deployment safety | DevOps, Release Engineers |
| `architecture/UI.md` | UI architecture patterns and component design | Frontend Engineers |
| `methodology/INCIDENT_RESPONSE.md` | Incident detection, escalation, and post-mortem practice | On-call Engineers |
| `methodology/RELEASE_MANAGEMENT.md` | Release planning, versioning, and change coordination | Release Managers |
| `methodology/METRICS.md` | Metric collection, alerting philosophy, and observability | SRE, Platform Engineers |
---
## 3. Guide Consumption Patterns
### 3.1 When to Consult a Guide
Not every task requires reading a methodology guide. The following signals indicate guide consultation is valuable:
**High-Value Guide Consumption Triggers:**
- First time performing a particular class of task (e.g., first architecture decision, first incident)
- Encountering a non-obvious failure mode that seems systemic
- Uncertainty about which subsystem to use for a given problem
- Receiving conflicting signals from different parts of the system
- Preparing to make a multi-step change with uncertain outcomes
- Onboarding to a new domain or responsibility area
- Writing a new methodology guide (meta-circular consumption)
**Low-Value Guide Consumption Triggers:**
- Routine tasks with established patterns
- Tasks that are explicitly routed by other documents
- Situations where the binding contracts are unambiguous
### 3.2 How to Read a Guide
Each guide follows a standard structure designed for skimming and targeted retrieval:
1. **Header Block**: Authority, Layer, Binding, Scope — determines applicability
2. **Mission Statement**: What problem this guide solves, in one paragraph
3. **Core Principles**: 3-5 principles that govern all subsequent guidance
4. **Practical Workflows**: Numbered steps for specific scenarios
5. **Examples**: Both success cases and failure modes with context
6. **Anti-Patterns**: Explicit warnings about what NOT to do and why
7. **Links Section**: Navigation to related documents
**Reading Order Recommendation:**
1. Read the Mission Statement first — confirm the guide is relevant
2. Scan Core Principles for the governing philosophy
3. Find the specific workflow or scenario most relevant to your task
4. Read the anti-patterns — these often clarify the principles
5. Check the Links section for related guidance
### 3.3 Guide Authority Boundaries
Methodology guides are explicitly non-binding. This has concrete implications:
**What Guides CAN Do:**
- Suggest workflows with SHOULD, PREFER, CONSIDER language
- Provide examples that illustrate successful patterns
- Describe tradeoffs without mandating choices
- Offer heuristics that work in common cases
- Acknowledge uncertainty and edge cases
**What Guides MUST NOT Do:**
- Use MUST, SHALL, REQUIRED for new requirements
- Create invariants that are not in `interfaces/CLAIMS.md`
- Define subsystem behavior that belongs in `core/PLUGINS.md`
- Contradict binding documents (guide is wrong in this case)
- Create proof obligations not registered in CLAIMS
---
## 4. Guide Authoring Standards
### 4.1 When to Create a New Guide
A new methodology guide should be created when:
1. **Recurring Scenario**: A class of tasks occurs frequently enough to warrant documented practice
2. **Non-Obvious Execution**: The correct approach is not apparent from first principles
3. **Tradeoff Complexity**: Multiple options exist with significant tradeoffs that require context to navigate
4. **Failure Pattern**: Similar failures occur that can be prevented with better guidance
5. **Knowledge Preservation**: Institutional knowledge about execution exists only in people's heads
**Indicators That a Guide is Needed:**
- Agents repeatedly ask the same clarifying questions
- Similar tasks are executed inconsistently by different agents
- Failure modes repeat across unrelated changes
- Onboarding to a domain requires extensive verbal explanation
- A TODO or issue pattern suggests a practice gap
### 4.2 Required Elements of a Methodology Guide
Every methodology guide MUST include:
**Header Block:**
```markdown
# GUIDE_NAME.md - Short Description
**Authority:** guidance (one-line description of what this guide covers)
**Layer:** Guides
**Binding:** No
**Scope:** what this guide covers
**Non-goals:** what this guide explicitly does NOT cover
```
**Mission Statement (§1):**
One paragraph explaining what problem this guide solves and why the guidance exists.
**Core Principles (§2):**
3-5 governing principles with explanations of WHY they exist. These are the reasoning behind the practice, not just the practice itself.
**Practical Workflows (§3):**
Numbered steps for common scenarios. Each step should include:
- What to do
- Why to do it (brief)
- What can go wrong
**Examples (§4):**
At least two examples:
1. A success case showing correct application of the guide
2. A failure case showing what breaks and why
**Anti-Patterns (§5):**
Explicit warnings about what NOT to do, with explanations of failure modes.
**Links Section (§N):**
Complete links section with Core Router, Authority, Registry, Contracts, Practice, and Operations links.
### 4.3 Style Guidelines
**Tone:**
- Direct and practical, not academic
- Uses active voice ("Run `decapod validate`" not "Validation should be run")
- Acknowledges uncertainty and edge cases honestly
- Explains the reasoning behind recommendations
**Terminology:**
- Use terms consistently as defined in `interfaces/GLOSSARY.md`
- Avoid jargon unless it's the accepted term in the domain
- Define domain-specific terms when first used
**Examples:**
- Include specific commands, not just descriptions
- Show actual output (or realistic mock output) when instructive
- Include error messages and what they mean
**Formatting:**
- Code blocks for commands and code
- Tables for comparisons and registries
- Numbered lists for workflows
- Bold for key terms and critical warnings
---
## 5. Boundary Rule
Methodology guides occupy a specific layer in the document hierarchy:
```
┌─────────────────────────────────────────────────────────────┐
│ Constitution Layer (specs/) - Binding Authority │
│ - INTENT.md: methodology contract │
│ - SYSTEM.md: system definition and authority doctrine │
│ - GIT.md: git workflow contract │
│ - SECURITY.md: security contract │
│ - AMENDMENTS.md: change control process │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Interfaces Layer (interfaces/) - Binding Machine Surfaces │
│ - CONTROL_PLANE.md: sequencing patterns │
│ - CLAIMS.md: promise registry │
│ - STORE_MODEL.md: state semantics │
│ - DOC_RULES.md: compilation rules │
│ - GLOSSARY.md: term definitions │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Guides Layer (methodology/, architecture/) - Non-Binding │
│ - SOUL.md: agent identity and behavior │
│ - ARCHITECTURE.md: architectural decision practice │
│ - TESTING.md: testing workflow │
│ - CI_CD.md: delivery automation practice │
│ - KNOWLEDGE.md: knowledge curation │
│ - MEMORY.md: memory hygiene │
│ - UI.md: UI architecture patterns │
└─────────────────────────────────────────────────────────────┘
```
**The boundary rule in practice:**
1. **If a binding document is ambiguous**, methodology guides provide contextual interpretation, but the interpretation must be consistent with the binding document's intent.
2. **If a guide conflicts with a binding document**, the binding document wins. The guide should be updated to reflect this.
3. **If a guide would create a new requirement**, the requirement must be registered in `interfaces/CLAIMS.md` and potentially elevated to an interface or spec.
4. **If a binding document references a guide**, the guide should be expanded to fully support that reference.
---
## 6. Cross-Guide Dependencies
Methodology guides form a dependency graph. Understanding these dependencies helps navigate the guide system effectively.
### 6.1 Primary Dependency Chain
```
SOUL.md (identity)
│
├──► ARCHITECTURE.md (how to make decisions)
│ │
│ ├──► TESTING.md (how to verify decisions)
│ │
│ └──► CI_CD.md (how to deliver decisions)
│
├──► KNOWLEDGE.md (how to preserve context)
│
└──► MEMORY.md (how to learn from experience)
```
### 6.2 Domain-Specific Guides
```
architecture/UI.md
│
├──► methodology/SOUL.md (component identity)
│
└──► methodology/ARCHITECTURE.md (architectural principles)
```
```
architecture/WEB.md
│
├──► methodology/ARCHITECTURE.md (API design principles)
│
└──► methodology/TESTING.md (integration testing patterns)
```
### 6.3 Cross-Guide Reference Patterns
When one guide references another, the reference should include:
- Document path
- Specific section (if applicable)
- Brief explanation of why the reference is relevant
**Example reference:**
> For memory hygiene patterns, see `methodology/MEMORY.md` §3 (Retrieval Discipline). The key insight is that memory should be pointers and residue, not comprehensive logs.
---
## 7. Guide Evolution
### 7.1 When to Update a Guide
Methodology guides should be updated when:
1. **Practice Changes**: The recommended approach has changed due to new tools, patterns, or understanding
2. **Failure Patterns Emerge**: Common failures suggest the current guidance is incomplete or incorrect
3. **Binding Documents Change**: When interfaces or specs change, guides that reference them must be updated
4. **New Examples Emerge**: Real-world examples (success or failure) should be captured
5. **Scope Expands**: A guide that was narrow grows to cover more territory
### 7.2 Update Process
1. **Read the current guide** in full
2. **Check binding documents** for relevant changes
3. **Identify specific sections** that need updating
4. **Draft changes** following the authoring standards
5. **Verify links** are still accurate
6. **Run validation**: `decapod validate` for structural validity
7. **Submit changes** following the amendment process for binding elements
### 7.3 Versioning and Changelog
For significant updates to methodology guides:
- Note the change in the document header (optional, not required for guides)
- Include a brief "Recent Changes" note if the guide has changed substantially
- If the change affects cross-guide dependencies, note the affected guides
---
## 8. Anti-Patterns
### 8.1 Guide Anti-Patterns
**The "Me Too" Guide**
- Copies structure from other guides without understanding why
- Includes generic advice that applies to any workflow
- Fails to capture domain-specific knowledge
**The Encyclopedia Guide**
- Attempts to cover every possible scenario
- Becomes so long that no one reads it
- Loses focus on the core mission
**The Command Manual**
- Lists commands without explaining when to use them
- Missing the "why" behind each step
- Becomes obsolete quickly as commands change
**The Contractual Guide**
- Uses MUST/SHALL language inappropriately
- Creates requirements without registering them
- Conflicts with binding documents
**The Orphaned Guide**
- No links to other documents
- No references from other documents
- Content becomes stale without anyone noticing
### 8.2 Consumption Anti-Patterns
**Guide Worship**
- Following a guide blindly without understanding the reasoning
- Applying guide recommendations to inappropriate contexts
- Treating guidance as binding when it is not
**Guide Rejection**
- Ignoring methodology guides entirely
- Assuming old patterns are still valid
- Dismissing guidance because "it doesn't apply here"
**Selective Consumption**
- Reading only the parts that confirm existing beliefs
- Ignoring anti-patterns and failure modes
- Taking examples out of context
### 8.3 Creation Anti-Patterns
**Requirements Creep**
- Adding binding requirements to a non-binding guide
- Registering claims without proper proof surfaces
- Contradicting binding documents
**Example Avoidance**
- Writing theoretical guidance without concrete examples
- Hiding failure modes instead of explaining them
- Avoiding discussion of tradeoffs
---
## 9. Specialized Domains
### 9.1 Architecture Practice
`methodology/ARCHITECTURE.md` is the primary guide for architectural decisions. It covers:
- Decision workflow (intent → constraints → options → tradeoffs → proof)
- Domain map navigation (data, caching, memory, web, cloud, etc.)
- Conway's Law alignment
- Migration-first design
- Debuggability requirements
**For domain-specific architecture:**
- `architecture/UI.md` — UI components, state management, rendering patterns
- `architecture/FRONTEND.md` — Frontend-specific architectural concerns
- `architecture/WEB.md` — API design, HTTP semantics, web security
- `architecture/DATA.md` — Data modeling, persistence, migration
- `architecture/SECURITY.md` — Threat modeling, security patterns
- `architecture/CLOUD.md` — Cloud deployment, scaling, resilience
### 9.2 Quality Assurance
`methodology/TESTING.md` covers the testing pyramid and change-coupled testing:
- Unit, integration, and E2E balance
- Test naming conventions
- Flaky test handling
- Evidence and reporting
**For binding testing contracts:**
- `interfaces/TESTING.md` — Machine-readable testing interface definitions
- `plugins/VERIFY.md` — Validation subsystem proof surfaces
### 9.3 Delivery Automation
`methodology/CI_CD.md` covers CI/CD pipelines and release hygiene:
- PR validation stages
- CD rollout strategies
- Branch hygiene
- Secret management
**For binding release contracts:**
- `specs/GIT.md` — Git workflow and branch management
- `plugins/VERIFY.md` — Proof surfaces for release validation
### 9.4 Knowledge and Memory
`methodology/KNOWLEDGE.md` and `methodology/MEMORY.md` together form the learning subsystem:
**Knowledge Management (KNOWLEDGE.md):**
- Capture discipline
- Curation workflow
- Lifecycle hygiene
- Provenance tracking
**Memory Management (MEMORY.md):**
- Memory creation and retrieval
- Confidence weighting
- Pruning and consolidation
- Distillation practices
**For binding knowledge contracts:**
- `interfaces/KNOWLEDGE_SCHEMA.md` — Schema definitions
- `interfaces/MEMORY_SCHEMA.md` — Memory schema definitions
- `interfaces/KNOWLEDGE_STORE.md` — Knowledge store semantics
### 9.5 Agent Identity and Behavior
`methodology/SOUL.md` defines agent persona and interaction patterns:
- Communication style (concise, precise, no artificial certainty)
- Behavioral defaults (smallest change, explicit assumptions)
- Boundary awareness (error handling in `EMERGENCY_PROTOCOL.md`)
**For emergency and error handling:**
- `core/EMERGENCY_PROTOCOL.md` — Emergency escalation procedures
---
## 10. Extraction Status
Dedicated files created for previously spliced contract content:
| `interfaces/TESTING.md` | Was embedded in methodology/TESTING.md | Binding machine surface needed separation |
| `core/EMERGENCY_PROTOCOL.md` | Was embedded in various docs | Emergency procedures needed dedicated canonical location |
| `interfaces/KNOWLEDGE_SCHEMA.md` | Was embedded in methodology/KNOWLEDGE.md | Binding schema needed separation |
| `interfaces/MEMORY_SCHEMA.md` | Was embedded in methodology/MEMORY.md | Binding schema needed separation |
| `interfaces/DEMANDS_SCHEMA.md` | Was embedded in core/DEMANDS.md | Binding schema needed separation |
---
## Links
### Core Router
- [core/DECAPOD.md](core/DECAPOD.md) - **Router and navigation charter (START HERE)**
- [core/ENGINEERING_EXCELLENCE.md](core/ENGINEERING_EXCELLENCE.md) - **Oracle for Engineering Standards (CTO->Principal)**
- [core/GAPS.md](core/GAPS.md) - Gap analysis methodology
### Authority (Constitution Layer)
- [specs/INTENT.md](specs/INTENT.md) - **Methodology contract (READ FIRST)**
- [specs/SYSTEM.md](specs/SYSTEM.md) - System definition and authority doctrine
- [specs/SECURITY.md](specs/SECURITY.md) - Security contract
- [specs/GIT.md](specs/GIT.md) - Git etiquette contract
- [specs/AMENDMENTS.md](specs/AMENDMENTS.md) - Change control
### Registry (Core Indices)
- [core/PLUGINS.md](core/PLUGINS.md) - Subsystem registry
- [core/INTERFACES.md](core/INTERFACES.md) - Interface contracts index
- [core/DEPRECATION.md](core/DEPRECATION.md) - Deprecation contract
- [core/DEMANDS.md](core/DEMANDS.md) - User demand patterns
### Contracts (Interfaces Layer)
- [interfaces/CONTROL_PLANE.md](interfaces/CONTROL_PLANE.md) - Sequencing patterns
- [interfaces/DOC_RULES.md](interfaces/DOC_RULES.md) - Doc compilation rules
- [interfaces/CLAIMS.md](interfaces/CLAIMS.md) - Promises ledger
- [interfaces/GLOSSARY.md](interfaces/GLOSSARY.md) - Term definitions
- [interfaces/STORE_MODEL.md](interfaces/STORE_MODEL.md) - Store semantics
- [interfaces/TESTING.md](interfaces/TESTING.md) - Testing contract
### Practice (Methodology Layer - This Registry)
- [methodology/SOUL.md](methodology/SOUL.md) - Agent identity and behavioral style
- [methodology/ARCHITECTURE.md](methodology/ARCHITECTURE.md) - Architecture practice
- [methodology/KNOWLEDGE.md](methodology/KNOWLEDGE.md) - Knowledge curation
- [methodology/MEMORY.md](methodology/MEMORY.md) - Memory and learning
- [methodology/TESTING.md](methodology/TESTING.md) - Testing practice and quality workflow
- [methodology/CI_CD.md](methodology/CI_CD.md) - CI/CD and release workflow practice
### Architecture Patterns (Domain Layer)
- [architecture/FRONTEND.md](architecture/FRONTEND.md) - Frontend architecture patterns
- [architecture/WEB.md](architecture/WEB.md) - Web architecture patterns
- [architecture/DATA.md](architecture/DATA.md) - Data architecture patterns
- [architecture/SECURITY.md](architecture/SECURITY.md) - Security architecture patterns
- [architecture/CLOUD.md](architecture/CLOUD.md) - Cloud deployment patterns
- [architecture/CACHING.md](architecture/CACHING.md) - Caching architecture patterns
- [architecture/MEMORY.md](architecture/MEMORY.md) - Memory architecture patterns
- [architecture/OBSERVABILITY.md](architecture/OBSERVABILITY.md) - Observability patterns
### Operations (Plugins Layer)
- [plugins/TODO.md](plugins/TODO.md) - Work tracking
- [plugins/VERIFY.md](plugins/VERIFY.md) - Validation subsystem
- [plugins/MANIFEST.md](plugins/MANIFEST.md) - Manifest patterns
- [plugins/KNOWLEDGE.md](plugins/KNOWLEDGE.md) - Knowledge subsystem
- [plugins/FEDERATION.md](plugins/FEDERATION.md) - Federation subsystem
- [plugins/EMERGENCY_PROTOCOL.md](plugins/EMERGENCY_PROTOCOL.md) - Emergency protocols