Dot File Audit

---
name: dotfile-audit
description: >-
  Use when you have an existing pipeline DOT file that needs review,
  fixing, or validation. Use when validation produces warnings or errors,
  when a DOT file was hand-written or generated by another tool, or when you want
  to verify a pipeline covers 100% of a spec before running it.
---

# dotfile-audit

Audit and fix pipeline DOT files. Catches structural issues, missing failure paths, spec gaps, and validation warnings.

## Checklist

1. Read the DOT file
2. Run structural audit (see Structural Checks below)
3. If a spec/design doc exists, run spec reconciliation (see Spec Reconciliation below)
4. Run `dotfile validate <file>.dot` — capture output
5. Fix all errors and warnings
6. Re-validate until clean (zero errors, zero warnings)
7. Present summary of what was found and fixed

## Structural Checks

Go through each check. Print results as a checklist.

### Graph Attributes
```
[ ] Has exactly one start node (shape=Mdiamond)
[ ] Has exactly one exit node (shape=Msquare)
[ ] Has `goal` attribute in graph block
[ ] Has `model_stylesheet` in graph block
[ ] Has `default_max_retry` in graph block
[ ] Has `retry_target` in graph block
[ ] Has `rankdir` in graph block
```

### Failure Paths (the most common issue)
For every `box` (codergen) node, verify it has at least one of:
- `goal_gate=true` AND `retry_target` set
- An outgoing edge with `condition="outcome=fail"` (or `outcome=FAIL`)

```
[x] plan — goal_gate=true, retry_target=plan
[x] setup — goal_gate=true, retry_target=setup
[ ] implement_feature — NO FAILURE PATH — fix needed
[x] verify_feature — has fail edge to implement_feature
```

**Fix:** For nodes missing a failure path, add `goal_gate=true` and `retry_target` pointing to the appropriate retry node (usually itself or the preceding implement node).

### Human Gates
For every `hexagon` node, verify:
- Has `type="wait.human"` attribute (shape alone is insufficient)
- Has outgoing edges with accelerator key labels (`[A] Approve`, `[R] Revise`, etc.)
- Has `condition` on each outgoing edge
- Happy path edge has `weight=2`

### Edge Conditions
For every `diamond` (conditional) node, verify:
- Has at least two outgoing edges
- Outgoing edges have `condition` attributes
- Success path has `weight=2`
- Uses valid condition syntax: `condition="outcome=success"`, `condition="outcome=fail"`

### Parallel Structure
If `component` (fan-out) nodes exist, verify:
- Each fan-out has a matching `tripleoctagon` (fan-in) node
- All parallel tracks connect from the fan-out and reconnect at the fan-in
- No edges skip the fan-in (would break synchronization)

### Prompt Quality (spot check)
Spot-check at least 3 `box` node prompts for:
- References `run.working_dir`
- Mentions specific tech stack (language, framework, deps)
- Includes TDD instruction ("Write failing test FIRST")
- Includes quality tool instructions (linter, formatter)
- Includes commit instruction with conventional commit format
- Is self-contained (doesn't reference other node outputs)

### Node Attributes
Check for invented attributes that the pipeline engine doesn't support:
- `join_policy`, `error_policy`, `max_parallel`, `default_choice` — these don't exist
- `tools`, `dependencies`, `inputs`, `outputs` — not valid pipeline attributes
- Any attribute not in the dotfile-from-spec reference tables

## Spec Reconciliation

If a spec or design doc is available, cross-reference:

**Phases → Nodes:**
Every phase listed in the spec has a corresponding DOT node.

**Components → Implement + Test + Commit:**
Every component has implement, test/verify, and commit nodes.

**Tech Stack → Prompts:**
Node prompts reference the correct language, framework, and dependencies.

**Quality Gates → Verify Prompts:**
Every quality tool (linter, formatter, type checker) appears in verify node prompts.

**Testing Frameworks → Test Prompts:**
Each test framework is referenced in the appropriate test node prompts.

**Parallelism → Fan-out/Fan-in:**
Parallel workstreams from the spec have matching `component`/`tripleoctagon` nodes.

**Models → Stylesheet + Classes:**
`model_stylesheet` reflects spec's model preferences. Nodes have correct `class` assignments.

**Human Gates:**
Gates match what the user requested (or no gates if they chose headless).

Print reconciliation results:
```
Phases:      8/8 covered
Components:  5/5 have implement+test+commit
Tech Stack:  3/3 prompts checked — all correct
Quality:     ruff [x] mypy [x] biome [x]
Testing:     pytest [x] vitest [x] playwright [x]
Parallelism: fan-out [x] fan-in [x] tracks match [x]
Models:      stylesheet [x] classes [x]
Gates:       0 requested, 0 present [x]
```

## Pipeline Validation

After structural fixes, run:

```bash
dotfile validate <file>.dot
```

**Errors** must be fixed — the pipeline won't run with errors.

**Warnings** should be fixed — they indicate potential runtime failures:
- "no outgoing fail edge" → add `goal_gate=true` + `retry_target` or an explicit fail edge
- "unreachable node" → fix edges or remove the node
- "goal_gate without retry_target" → add `retry_target`

**Target: zero errors AND zero warnings.**

## Common Issues and Fixes

| Issue | Fix |
|-------|-----|
| Box node with no failure path | Add `goal_gate=true, retry_target="node_name"` |
| Hexagon without `type="wait.human"` | Add `type="wait.human"` attribute |
| Diamond with only one outgoing edge | Add the missing success or fail edge |
| Prompts missing `run.working_dir` | Add `run.working_dir` reference to every build/verify prompt |
| Invented attributes | Remove them — only use attributes from the dotfile-from-spec reference |
| Fan-out without matching fan-in | Add `tripleoctagon` fan-in node and connect parallel tracks |
| `model_stylesheet` outside graph block | Move into `graph [ ... ]` block |
| Conditions using wrong case | Use `outcome=success` / `outcome=fail` (case-insensitive but be consistent) |
| Missing commit nodes | Add explicit commit node after each implement+verify phase |
| Prompts not self-contained | Expand prompts to include all context — they execute in isolation |