┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   ORGANON   │         │     RFC     │         │    CODE     │
│ "should be" │ ◄─────► │ "will be"   │ ────────► │  "what is"  │
│             │  cites  │             │ implements│             │
│ Constraints │         │ Proposals   │           │ Reality     │
└─────────────┘         └─────────────┘           └─────────────┘

# Determine next RFC number
ls rfcs/*.md | sort | tail -1  # Get latest number
# Create new RFC (e.g., RFC 002)
touch rfcs/002-<feature-name>.md

---
type: rationale
scope: product
name: [feature-name]
version: "1.0"
summary: [One-sentence description]
token_estimate: [estimate ~5000-8000 for domain RFCs]
status: draft
created: [YYYY-MM-DD]
author: [your-agent-name]
related_files:
  - ../organon/domains/tools/ETHOS.md  # or appropriate product ETHOS
  - ../book-llms/[relevant].md
load_priority: high
audience: [llm, human]
---

## Organon Impact

### Create

**`organon/domains/<name>/ETHOS.md`** ← Core domain definition

This file defines the <name> domain's identity and constraints:

\```markdown
## Identity

### What This Domain IS
- [Specific identity statement 1]
- [Specific identity statement 2]
- [Specific identity statement 3]
- [What it provides / what problem it solves]
- [What it integrates with]

### What This Domain IS NOT
- [Clear boundary 1 - what it explicitly does NOT do]
- [Clear boundary 2]
- [Clear boundary 3]
- [What it is not responsible for]

## Invariants

1. **INV-<SCOPE>-1: <kebab-case-name>**
   - [Exact invariant text - what constraint must hold]
   - Enforced by: [Specific enforcement mechanism - tests, gates, reviews]

2. **INV-<SCOPE>-2: <kebab-case-name>**
   - [Exact invariant text]
   - Enforced by: [Specific enforcement mechanism]

3. **INV-<SCOPE>-3: <kebab-case-name>**
   - [Exact invariant text]
   - Enforced by: [Specific enforcement mechanism]

[Minimum 3 invariants, typically 5-7 for a domain]

## Principles (Prioritized)

1. **[Principle 1] over [alternative 1]** - [One-line explanation]
2. **[Principle 2] over [alternative 2]** - [One-line explanation]
3. **[Principle 3] over [alternative 3]** - [One-line explanation]
4. **[Principle 4] over [alternative 4]** - [One-line explanation]
5. **[Principle 5] over [alternative 5]** - [One-line explanation]

[Prioritized list - 1 is most important]

## Decision Heuristics

| Situation | Action |
|-----------|--------|
| [Specific scenario 1] | [Clear action / decision] |
| [Specific scenario 2] | [Clear action / decision] |
| [Specific scenario 3] | [Clear action / decision]|
| [Specific scenario 4] | [Clear action / decision] |
| [Specific scenario 5] | [Clear action / decision] |

[Minimum 5 heuristics covering common decision points]
\```

**`organon/domains/<name>/PHILOSOPHY.md`** ← Design rationale

This file explains WHY the <name> domain is designed this way:

\```markdown
## The Problem

[Detailed problem description - 2-3 paragraphs]

**Why does this problem exist?**
1. [Root cause 1]
2. [Root cause 2]
3. [Root cause 3]

**Why haven't we solved it yet?**
- [Historical reason or blocker]

**Result:** [Negative outcome of unsolved problem]

## The Bet

**Bet:** [One-sentence statement of what assumption we're making]

**Why this works:**
- [Evidence point 1]
- [Evidence point 2]
- [Evidence point 3]

**What must be true:**
- [Prerequisite 1 for bet to succeed]
- [Prerequisite 2]
- [Prerequisite 3]

## Trade-offs

### 1. [Trade-off Name] ([Choice A] > [Choice B])
**Choice:** [What we decided]

**Benefit:** [What we gain]

**Cost:** [What we give up]

**Why we chose [X]:** [2-3 sentence rationale]

### 2. [Trade-off Name]
[Same structure]

### 3. [Trade-off Name]
[Same structure]

### 4. [Trade-off Name]
[Same structure]

### 5. [Trade-off Name]
[Same structure]

[Minimum 5 trade-offs - major design decisions]

## Alternatives Considered

### Alt 1: [Alternative Approach Name]
**Rejected because:** [Clear reason why this won't work]

### Alt 2: [Alternative Approach Name]
**Rejected because:** [Clear reason]

### Alt 3: [Alternative Approach Name]
**Rejected because:** [Clear reason]

## Success Criteria

This bet succeeds if:
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]
- [ ] [Measurable outcome 4]
\```

### Update

**`<product-path>/ETHOS.md`** (product-level organon)
- Add reference: "<name> domain inherits product invariants"
- Add decision heuristic: "Working on <name>? Read organon/domains/<name>/ETHOS.md"

**`<product-path>/README.md`**
- Add link to <name> domain in "Domains" section

**`book-llms/[relevant-file].md`** (if applicable)
- Add <name> as reference implementation example
- Update relevant patterns/specifications

## Technical Implementation

### Architecture

**Package Structure:**
\```
<product>/
├── organon/
│   └── domains/
│       └── <name>/
│           ├── ETHOS.md      ← Domain constraints
│           ├── PHILOSOPHY.md ← Design rationale
│           └── README.md     ← Navigation
└── src/
    └── [implementation-path]/
        ├── core/              ← Pure functions
        ├── [subdirs]          ← Domain-specific modules
        └── index.ts           ← Public API
\```

**Core Abstractions:**
\```typescript
// Show key types/interfaces that implement domain concepts
interface [CoreConcept1] {
  // ...
}

interface [CoreConcept2] {
  // ...
}

type [CoreAbstraction] = ...
\```

**Implements domain invariants:**
- **INV-<SCOPE>-1** ([name]): [How code enforces this constraint]
- **INV-<SCOPE>-2** ([name]): [How code enforces this constraint]
- **INV-<SCOPE>-3** ([name]): [How code enforces this constraint]
[Map each invariant to implementation strategy]

### API Design

**Core API** (implements domain principles):

\```typescript
// Show actual function signatures, interfaces, types

// Main entry point
export function [primaryFunction](options: [Options]): Promise<[Result]> {
  // ...
}

// Options interface
export interface [Options] {
  [field1]: [type];
  [field2]: [type];
  // ...
}

// Result interface
export interface [Result] {
  success: boolean;
  [data]: [type];
  [errors]?: Error[];
}

// Supporting functions
export function [helperFunction1](...): Promise<...>
export function [helperFunction2](...): Promise<...>
\```

**API Design Principles:**
- [How API reflects domain principles]
- [Why options object vs positional args]
- [Why async vs sync]

### Implementation Plan

**Phase 1: [Name] (Weeks X-Y)**

**Week X: [Milestone Name]**
- [ ] [Specific task 1]
- [ ] [Specific task 2]
- [ ] [Specific task 3]
- [ ] [Specific task 4]

**Week Y: [Milestone Name]**
- [ ] [Specific task 5]
- [ ] [Specific task 6]
- [ ] [Specific task 7]

**Deliverable:** [What ships in Phase 1 - specific, testable]

---

**Phase 2: [Name] (Weeks A-B)**
- [ ] [Task 8]
- [ ] [Task 9]
- [ ] [Task 10]

**Deliverable:** [What ships in Phase 2]

---

**Phase 3: [Name] (Weeks C-D)**
- [ ] [Task 11]
- [ ] [Task 12]

**Deliverable:** [What ships in Phase 3]

### Design Decisions (Technical)

These decisions implement the domain principles defined in <name>/PHILOSOPHY.md:

**Decision 1: [Technical Choice Name]**
- **Implements:** [Which domain principle or invariant]
- **Technical benefit:** [What this enables technically]
- **Trade-off:** [What we're giving up]
- **Why we chose [X]:** [2-3 sentence rationale]

**Decision 2: [Technical Choice Name]**
[Same structure - minimum 5 decisions]

## Success Metrics
- [ ] **[Metric 1]** - [Measurable, specific]
- [ ] **[Metric 2]** - [Measurable, specific]
- [ ] **[Metric 3]** - [Measurable, specific]

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk 1] | [High/Med/Low] | [Specific mitigation strategy] |

## Open Questions
1. **[Question 1]** - [What's uncertain?]
   - **Recommendation:** [Suggested resolution]

## Dependencies
**Blocks:** [What can't happen until this is done]
**Blocked by:** [What must happen first]

## Organon Impact
- Create testing/ETHOS.md (will add invariants)
- Create testing/PHILOSOPHY.md (will explain design)

## Technical Implementation
[5000 words of architecture, API, phases]

## Organon Impact
[Detailed ETHOS.md and PHILOSOPHY.md content]

## Technical Implementation
We will implement the constraints defined above.

1. **INV-TEST-1: quality**
   - Code should be high quality
   - Enforced by: reviews

1. **INV-TEST-1: 100-percent-coverage**
   - Testing domain itself has 100% test coverage
   - Enforced by: Vitest coverage gate in CI (fails build < 100%)

### What This Domain IS
- A good testing framework
- Well-designed and useful
- Follows best practices

### What This Domain IS
- A semantic testing framework for tier-4 invariant verification
- TypeScript-native library published as @organon/testing
- Bridge between "declare invariant in ETHOS.md" and "verify in code"
- Integration layer connecting invariants to test frameworks (not a test runner)
- Coverage tracker that maps invariant IDs to test implementations

## Principles
- Clarity
- Speed
- Simplicity
- Testability
- Flexibility

## Principles (Prioritized)
1. **Testability over speed** - Pure functions, deterministic
2. **Clarity over brevity** - Verbose errors, explicit API
3. **Reusability over flexibility** - Pre-built assertions for 80% cases
4. **Fail-fast over forgiving** - Errors surface immediately
5. **Integration over replacement** - Works with existing test frameworks