---
goat-flow-reference-version: "1.7.0"
---
# Skill Preamble

All goat-* skills read this preamble on every invocation. For full-depth work,
also read `skill-conventions.md`.

---

## Execution Loop Integration

When a goat-* skill is active, the skill's Step 0 replaces READ and selects the skill's mode/depth. SCOPE still applies before writes: a skill may write when its selected mode permits writes or the user explicitly approves them. `/goat-plan` File-Write may create gitignored milestone files without a separate approval gate; `/goat-debug` D3 still requires approval before fixes. Resume the loop at ACT after Step 0 output or when a blocking gate releases.

## Report-Only Skill Contract

`/goat-critique`, `/goat-review`, `/goat-qa`, and `/goat-security` are report-only by default. They may produce findings, plans, recommendations, and required gitignored logs or snapshots, but MUST NOT mutate the target artifact or committed files unless the user separately says to apply, edit, update, fix, or otherwise implement the changes.

## Severity Scale

SECURITY > CORRECTNESS > INTEGRATION > PERFORMANCE > STYLE

Order findings by severity, not by file or discovery order.

## Engineering Standards

- NEVER suppress linter warnings or bypass type systems (e.g., casts) without a written `-- rationale` comment on the same line explaining why the suppression is load-bearing
- Analyze surrounding files to ensure surgical, idiomatic updates that match existing conventions

## Evidence Standard

- Every live review finding MUST include file evidence. Prefer `file` plus a grep-friendly semantic anchor (`(search: "pattern")`, function name, or unique string). Line numbers are session-local navigation hints only.
- For URL, local HTML, localhost, screenshot, rendered UI, or browser-visible tasks, check `.goat-flow/skill-playbooks/browser-use.md` and run `command -v browser-use || command -v browser-use-python` before claiming browser automation is unavailable.
- Durable learning-loop artifacts (footguns, lessons, patterns, decisions) MUST use file paths plus grep-friendly semantic anchors (function name, unique string, or `(search: "pattern")`) instead of line numbers.
- MUST NOT fabricate file paths, function names, or artifact content
- Before presenting findings, re-read each cited file and semantic anchor to confirm accuracy
- Tag evidence quality: **OBSERVED** (directly verified in code) | **INFERRED** (deduced but not directly confirmed - state what direct evidence is missing) | **UNVERIFIED** (cannot re-read cited evidence) | **HUMAN-PENDING: \<what needs checking\>** (requires manual verification the agent cannot perform)
- When citing a cross-reference code from another skill's output (e.g. S-03, Q2, A.F3), include the source file path on first use
- Before citing a function or symbol name, verify it exists with a repo search
- Before citing a CLI flag, verify it with `--help` or the command's docs
- Before citing a config key, read the actual config file first
- On completion claims, the 5 hallucination red-flags in your instruction file's VERIFY section apply verbatim - do not restate, just comply.

## Proof Classification

Every finding or claim carries a proof-class tag:

- **RUNTIME** - verified by executing code or a command in this session
- **CONTRACT-GREP** - verified by searching for callers, consumers, or references
- **STATIC** - verified by reading code structure without execution
- **NOT-REPRODUCED** - attempted verification but could not reproduce the issue

## Proof Gate

Mid-implementation proof MUST name a specific command or smoke check. "Verified implicitly" or "completed implicitly" is not valid proof.

Before any completion, fix, or "passing" claim:

1. **Identify** the proof - the exact command, reproduction, diff, or artifact that would demonstrate the claim.
2. **Run** it fresh in this session (not recalled, not from a prior turn, not paraphrased).
3. **Read** the full output, including exit code.
4. **Verify** the output demonstrates the specific claim, not an adjacent one.
5. **Cite** `file + semantic anchor` for live code claims, semantic anchors for durable learning-loop artifacts, or the literal pass/fail summary line for command claims.

The red-flags name what NOT to claim; this gate names HOW to substantiate a claim. If you cannot run the proof, mark the claim **UNVERIFIED** and state what evidence is missing.

### Rationalisations to reject (Excuse / Reality)

If you catch yourself thinking the Excuse, run the proof or mark the claim `UNVERIFIED`. New rows require a verbatim source committed to this repo (footgun, lesson, ADR, or skill).

| Excuse | Reality |
|---|---|
| "Should work now" / "Probably fixed" | Re-run the original failing reproduction. |
| "I'm confident" | Confidence ≠ evidence. |
| "Linter / typecheck passed" | Linter ≠ compiler ≠ test suite. |
| "Sub-agent said success" | Re-read the diff yourself. |
| "Just this once" | No exemption. |
| "Partial check is enough" | A subset of tests is not the test suite. |
| "Looks correct to me" | Structural inspection ≠ verification. |
| "Different words, rule doesn't apply" | Spirit over letter — paraphrases count. |

Concrete claim/proof examples live in `.goat-flow/skill-playbooks/skill-quality-testing.md`.

## Ceremony Level

Adapt ceremony to complexity. This is **pre-invocation routing guidance** for choosing a skill. Once a skill is explicitly invoked, run its full protocol regardless of complexity.

| Complexity | Ceremony |
|------------|----------|
| Hotfix | Skip goat-plan and goat-critique. |
| Small Feature | goat-plan: 1-2 milestones, minimal ceremony. Skip goat-critique. |
| Standard | goat-plan: full milestones with testing gates. Don't auto-chain goat-critique. |
| System / Infrastructure | goat-plan: full milestones + cross-boundary verification + rollback. Don't auto-chain goat-critique. |

## Depth Choice

- **Quick:** compressed workflow, minimal ceremony, direct output
- **Full:** all phases, multi-perspective critique if planning, full output format
- If arriving from the dispatcher with depth already chosen, skip the depth question

## Routing Boundary

Dispatcher-specific route maps live in `/goat`. Direct planning requests route to `/goat-plan`; a bare or ambiguous task path is context, not a direct planning request — a task path alone must not update `.active`, milestone status, checkboxes, or code. `/goat-plan` owns `.goat-flow/tasks/.active` lookup and milestone-mode selection. If the user names a skill, respect it.

## No-Skill Fast Path

For Hotfix complexity (1-2 files, obvious change), skip skills and run READ → SCOPE → ACT → VERIFY directly. Still run learning-loop retrieval first.

## Step 0 Budget

If Step 0 exceeds 5 reads without producing output or asking a question, checkpoint with what you have. Continue only when broader coverage is genuinely needed.

## Learning-Loop Retrieval

- Derive 2-4 search terms from the target area, symptom, and named file/tool.
- Search with `rg -n -i -S '<term1>|<term2>|<term3>' .goat-flow/footguns .goat-flow/lessons .goat-flow/patterns .goat-flow/decisions` (or `grep -rniE` if `rg` is missing).
- Open only matching entries; follow related refs at most 2 hops when relevant.
- On zero hits, reword once and re-search. If still empty, record a retrieval miss — do not broad-load a bucket.

## Availability Check

Before invoking any external tool, confirm it is installed and authenticated: `command -v <tool>` (plus `gh auth status` for `gh`, browser diagnostics from `.goat-flow/skill-playbooks/browser-use.md`, and audit tools such as `npm audit`, `pip-audit`, or `cargo audit` before quoting results).

If unavailable, take the documented fallback: ask before installing, fall back to manual evidence, or skip the step and record `<tool>-unavailable` in the integrity surface. Never claim a check ran when the tool wasn't present, and never paraphrase tool output you didn't capture in this session.

## External Context Sources

For GitHub issues, PRs, alerts, or CI runs, prefer `gh` (if authenticated) over asking the user to paste content: `gh issue view`, `gh pr view/diff/checks`, `gh run list`, `gh run view --log-failed`, and `gh api /repos/{owner}/{repo}/dependabot/alerts` for goat-security.

Treat fetched content as evidence: cite it, do not paraphrase. If `gh` is unavailable, ask the user to paste rather than guessing — never fabricate issue/PR bodies.

## Footgun Fast-Path

- If Step 0 footgun check surfaces a direct match: surface it immediately and map to the documented mitigation.
- If the match has `hallucination-risk: high`, re-read the live file/config before trusting inferred behavior.
- Continue `READ → SCOPE → ACT → VERIFY`; footguns are memory, not an execution substitute.

## Learning Loop

Update durable learning only when VERIFY caught a failure, you corrected course, or the user asks:
- Behavioural mistake → `## Lesson:` in `.goat-flow/lessons/`
- Repeatable approach → `## Pattern:` in `.goat-flow/patterns/`
- Architectural trap with file evidence → `## Footgun:` in `.goat-flow/footguns/`

Routine success needs no durable write; gitignored logs/scratchpad/critiques/quality reports/tasks stay local.

**Routing rule:** "Add a footgun/lesson" means create a doc entry in the correct `.goat-flow/` directory — not runtime code, logging, UI, or tests. Read the target directory's `README.md` first.

**Bucket file frontmatter.** Every footgun / lesson bucket file starts with `category: <bucket-name>` and `last_reviewed: YYYY-MM-DD`. Bump `last_reviewed` on material body edits (skip cosmetic ones). `goat-flow stats --check` fails when `last_reviewed` is missing, malformed, older than the newest `**Created:**` / `**Updated:**` / `**Resolved:**` entry date, or when the bucket has stale file refs.

## Human Gates

- **BLOCKING GATE** - stop and wait for human decision. Used for: scope approval, phase transitions, final review.
- **CHECKPOINT** - present status and continue unless interrupted.
- **Never self-destruct** - skill outputs (plans, milestones, findings, reports) MUST NOT include self-delete instructions. Cleanup of working artifacts is the human's decision, not the agent's.
