# PLAYBOOK.md — Decision Frameworks and Failure Modes

## Links

- [core/DECAPOD.md](../../core/DECAPOD.md) - **Router and navigation charter (START HERE)**
- [core/EMERGENCY_PROTOCOL.md](../../core/EMERGENCY_PROTOCOL.md) - Emergency protocols

## When Stuck: Triage Flow

```
1. Is the task clear?
   NO  → Re-read the task description. Check `decapod todo get --id <id>`.
         Still unclear? Ask the user. Do not guess.

2. Does `decapod validate` pass?
   NO  → Fix validation failures first. They are the authoritative gate.
         Read the failure messages — they tell you exactly what's wrong.

3. Do tests pass?
   NO  → Fix failing tests. Cite the test name and error.
         Do not disable tests to make progress.

4. Is the change on the right branch?
   NO  → `decapod workspace ensure`. Never work on main/master.

5. Is the scope creeping?
   YES → Stop. Finish the current scope. File new tasks for extras.

6. Is the approach getting hacky?
   YES → Stop. Revisit the plan. Consider a simpler approach.
```

## Decision Frameworks

### Does this meet the Oracle's Standard?

```
Does this change align with the CTO/SVP/Architect/Principal standards in ENGINEERING_EXCELLENCE.md?
  YES → Proceed with implementation.
  NO  → Stop. Refactor the approach to meet the industry-defining standards of the Oracle.
```

### Should I Create a New File?

```
Can I accomplish the goal by editing an existing file?
  YES → Edit the existing file.
  NO  → Is the new file required for the task?
    YES → Create it. Follow existing naming conventions.
    NO  → Do not create it.
```

### Should I Add a Dependency?

```
Does an existing dependency already cover this?
  YES → Use the existing dependency.
  NO  → Is the dependency well-maintained and small?
    YES → Add it to Cargo.toml. Run `cargo update`. Commit Cargo.lock.
    NO  → Can I implement the needed functionality in < 50 lines?
      YES → Implement it inline.
      NO  → Add the dependency, but document why in the commit message.
```

### Should I Refactor Surrounding Code?

```
Was the refactoring explicitly requested?
  YES → Do it.
  NO  → Is the surrounding code blocking the current task?
    YES → Refactor the minimum needed to unblock.
    NO  → Do not refactor. File a separate task if it's important.
```

### Core vs Plugin?

```
Does the change affect state integrity, validation, or the broker?
  YES → Core change. Requires extra tests. Keep minimal.
  NO  → Plugin change. This is where 90% of work happens.
```

## Common Failure Modes

### "I'll just quickly fix this too"
**Problem**: Scope creep. Unrelated changes mixed into a task.
**Fix**: One task, one scope. File new tasks for discovered issues.

### "The tests are too strict"
**Problem**: Tests encode invariants. Weakening them is a regression.
**Fix**: If a test is wrong, explain why and fix the test. If the test is right, fix your code.

### "I need to restructure everything first"
**Problem**: Premature abstraction. Over-engineering before understanding.
**Fix**: Make it work, make it right, make it fast — in that order. Ship the smallest correct change.

### "decapod validate is failing on something unrelated"
**Problem**: Existing drift in the repo.
**Fix**: If truly unrelated, note it and file a task. Do not ignore it. Do not disable the gate.

### "I can't test this change"
**Problem**: Missing test infrastructure.
**Fix**: Add the test. Even a smoke test is better than no test. Mark untestable claims as `partially_enforced`.

### "The session expired"
**Problem**: Decapod sessions have TTLs.
**Fix**: Run `decapod session acquire` again. Re-export the environment variables.

## Evidence Standards

When claiming a task is done, provide:

1. **What changed**: File paths and line ranges.
2. **Why it changed**: Link to task/issue/spec.
3. **Proof**: Which tests pass. Which gates are green. Exact command + output.
4. **Gaps**: What is NOT covered. What remains aspirational.

Example:
```
Changed: src/core/validate.rs:45-62
Why: Fixes #123 — namespace purge gate was not checking plugins/
Proof: `cargo test --locked test_namespace_purge` passes (was failing)
       `decapod validate` passes (was failing on namespace gate)
Gaps: Does not cover dynamically loaded plugins (filed as task R_xxx)
```
