ghe-design

What this skill does

## IRON LAW: User Specifications Are Sacred

**THIS LAW IS ABSOLUTE AND ADMITS NO EXCEPTIONS.**

1. **Every word the user says is a specification** - follow verbatim, no errors, no exceptions
2. **Never modify user specs without explicit discussion** - if you identify a potential issue, STOP and discuss with the user FIRST
3. **Never take initiative to change specifications** - your role is to implement, not to reinterpret
4. **If you see an error in the spec**, you MUST:
   - Stop immediately
   - Explain the potential issue clearly
   - Wait for user guidance before proceeding
5. **No silent "improvements"** - what seems like an improvement to you may break the user's intent

**Violation of this law invalidates all work produced.**

## Background Agent Boundaries

When running as a background agent, you may ONLY write to:
- The project directory and its subdirectories
- The parent directory (for sub-git projects)
- ~/.claude (for plugin/settings fixes)
- /tmp

Do NOT write outside these locations.

---

## GHE_REPORTS Rule (MANDATORY)

**ALL reports MUST be posted to BOTH locations:**
1. **GitHub Issue Thread** - Full report text (NOT just a link!)
2. **GHE_REPORTS/** - Same full report text (FLAT structure, no subfolders!)

**Report naming:** `<TIMESTAMP>_<title or description>_(<AGENT>).md`
**Timestamp format:** `YYYYMMDDHHMMSSTimezone`

**ALL 11 agents write here:** Athena, Hephaestus, Artemis, Hera, Themis, Mnemosyne, Hermes, Ares, Chronos, Argos Panoptes, Cerberus

**REQUIREMENTS/** is SEPARATE - permanent design documents, never deleted.

**Deletion Policy:** DELETE ONLY when user EXPLICITLY orders deletion due to space constraints.

---

# GHE Design Skill for Athena

## Core Philosophy: Requirements Are Free-Form

**CRITICAL**: Requirements documents are NOT constrained by templates.

Every domain has unique needs:
- **Mathematical specifications** need formal notation, proofs, invariants
- **Game mechanics** need interaction flows, state machines, physics models
- **Financial systems** need legal bounds, compliance protocols, audit trails
- **Distributed architectures** need consistency models, failure modes, CAP tradeoffs
- **Security specifications** need threat models, attack surfaces, trust boundaries
- **UI/UX features** need wireframes, accessibility, responsive behavior
- **Data pipelines** need schemas, transformations, validation rules
- **Hardware interfaces** need timing diagrams, protocols, signal specifications
- **Legal/compliance** need regulatory references, audit requirements, retention policies

**Athena writes requirements in whatever structure best serves the domain.**

The REQ-TEMPLATE.md is a **reference of possible sections**, not a mandatory structure. Use what's relevant, ignore what's not, add what's missing.

---

## Guiding Principles

### 1. Clarity Over Format
The goal is for Hephaestus to understand WHAT to build. Structure serves clarity, not the reverse.

### 2. Domain-Appropriate Language
Write in the language of the domain:
- Mathematical notation for algorithms
- State diagrams for interactive systems
- Legal language for compliance
- Network diagrams for distributed systems
- Threat models for security
- Timing diagrams for real-time systems
- Entity relationships for data models

### 3. Completeness Over Brevity
Include everything needed to implement. If Hephaestus will have questions, answer them preemptively.

### 4. References Over Repetition
Link to external documentation, specifications, standards. Don't copy-paste entire RFCs or API docs.

### 5. Verifiable Acceptance
Every requirement should have a way to verify it was met. "Working correctly" is not verifiable. "Returns HTTP 200 with JSON payload matching schema X" is verifiable.

---

## What MUST Be Present

Despite free-form structure, every requirements document MUST have:

1. **Clear identification**: REQ-NNN with version
2. **What is being built**: Unambiguous description
3. **Why it's needed**: User story or business justification
4. **How to verify completion**: Acceptance criteria (testable)
5. **External references**: Links to APIs, specs, assets, related issues

Everything else is domain-dependent.

---

## Domain-Specific Patterns

### Pattern: Mathematical/Algorithmic

```markdown
# REQ-042: Collision Detection Algorithm

## Problem Statement
Detect collisions between N convex polygons in 2D space.

## Mathematical Foundation
Using the Separating Axis Theorem (SAT):
- For convex polygons P and Q
- If there exists an axis where projections don't overlap → no collision
- Test all edge normals of both polygons

## Invariants
- Algorithm MUST be O(n*m) where n,m are vertex counts
- False positives: 0 (exact detection)
- False negatives: 0 (no missed collisions)

## Edge Cases
- Touching edges (0 penetration) → collision = true
- Nested polygons → collision = true
- Degenerate polygons (< 3 vertices) → undefined behavior

## References
- [SAT Explanation](https://www.sevenson.com.au/programming/sat/)
- [GJK Alternative](https://blog.winter.dev/2020/gjk-algorithm/)
```

### Pattern: Game Mechanics

```markdown
# REQ-043: Player Jump Mechanic

## State Machine
```
GROUNDED → (jump pressed) → JUMPING
JUMPING → (apex reached) → FALLING
FALLING → (ground contact) → GROUNDED
JUMPING/FALLING → (wall contact) → WALL_SLIDING
WALL_SLIDING → (jump pressed) → WALL_JUMPING
```

## Physics Parameters
- Jump velocity: 12 m/s
- Gravity: 35 m/s² (falling), 20 m/s² (rising)
- Coyote time: 100ms
- Jump buffer: 150ms

## Feel Requirements
- Jump must feel "snappy" not "floaty"
- Variable jump height based on button hold duration
- Reference: Celeste jump feel

## Assets Required
- Jump sound: `assets/sfx/jump.wav`
- Land sound: `assets/sfx/land.wav`
- Particle effect: `assets/vfx/jump_dust.prefab`
```

### Pattern: Financial/Legal

```markdown
# REQ-044: Payment Processing

## Regulatory Compliance
- PCI DSS Level 1 (we never store card numbers)
- GDPR Article 17 (right to erasure of payment history)
- SOX compliance for audit trails

## Transaction Flow
1. User initiates payment
2. Create idempotency key (UUID v4)
3. Call Stripe PaymentIntent API
4. On success: record transaction, send receipt
5. On failure: log error, notify user, DO NOT retry automatically

## Legal Constraints
- Refunds MUST be processed within 5 business days
- Transaction records retained for 7 years
- User can request payment history export (JSON format)

## Audit Requirements
- Every transaction logged with: timestamp, user_id, amount, status, idempotency_key
- Logs immutable (append-only)
- Access to logs restricted to finance role

## References
- [PCI DSS Requirements](https://www.pcisecuritystandards.org/)
- [Stripe API](https://stripe.com/docs/api/payment_intents)
- Internal: `docs/legal/payment-policy.pdf`
```

### Pattern: Distributed Systems

```markdown
# REQ-045: Event Sourcing System

## Consistency Model
- Event store: strongly consistent (single leader)
- Read models: eventually consistent (< 500ms lag acceptable)
- Partition tolerance: yes (events replicated across 3 zones)

## CAP Tradeoffs
Prioritize: Consistency + Partition Tolerance
Sacrifice: Availability during network partitions

## Failure Modes
| Failure | Detection | Response |
|---------|-----------|----------|
| Leader down | Heartbeat timeout (3s) | Promote follower |
| Network partition | Split-brain detection | Reject writes on minority |
| Disk full | Monitoring alert | Stop accepting events |

## Event Schema
```json
{
  "event_id": "uuid",
  "aggregate_id": "uuid",
  "sequence": "int64",
  "type": "string",
  "payload": "json",
  "timestamp": "iso8601",
  "metadata": {"causation_id": "uuid", "correlation_id": "uuid"}
}
```

## References
- [Event Sourcing Pattern](https://martinfowler.com/eaaDev/EventSourcing.html)
- [CQRS](https://martinfowler.com/bliki/CQRS.html)
```

### Pattern: Security

```markdown
# REQ-046: Authentication System

## Threat Model
| Threat | Likelihood | Impact | Mitigation