Fable Adversarial Reviews

_fable-audits.txt

# adversarial audit prompts - fetch & run
#
# This gist contains three generic audit prompts:
# - fable-audit-codebase.txt: codebase/implementation audit.
# - fable-audit-docs.txt: documentation audit.
# - fable-audit-process.txt: end-to-end workflow/process audit.
#
# These files are /goal specs. The launcher below only NAMES the file; the agent
# opens it with its own Read tool, so the ~4KB /goal size limit never touches the
# prompt body. Keep the launcher tiny and let the file on disk carry the detail.
#
# -- 1. Fetch every file in this gist into ./.prompts/ (no nested .git inside your repo) --
# Run from your repo root. Re-run the same command to update (overwrites).

git clone --depth 1 https://gist.github.com/04970a2b8d9cc419de3ba05b9a03db5a.git /tmp/_p \
  && mkdir -p .prompts && cp /tmp/_p/*.txt .prompts/ && rm -rf /tmp/_p

#
# gh alternative (no git at all, auto-picks up new files):

mkdir -p .prompts && gh gist view 04970a2b8d9cc419de3ba05b9a03db5a --files \
  | while IFS= read -r f; do gh gist view 04970a2b8d9cc419de3ba05b9a03db5a -f "$f" -r > ".prompts/$f"; done

# -- 2. Run an audit - paste this /goal, swapping <PATH_TO_PROMPT> --
#   .prompts/fable-audit-codebase.txt
#   .prompts/fable-audit-docs.txt
#   .prompts/fable-audit-process.txt
#
# Relative paths assume you launch from the dir you cloned into; use an absolute
# path if CWD is uncertain.

/goal Read <PATH_TO_PROMPT> in full and execute its instructions to the letter - that file is your task spec, not reference to summarize or improve. Stay strictly within the scope it defines: make no change it doesn't authorize, and do not commit, push, or touch git state. Not done until its Output/stop criteria are met exactly as written.

fable-audit-codebase.txt

/goal Perform an exhaustive, adversarial audit of this entire codebase -- surfacing not just defects but design incoherences, unexpected affordances, doc drift, and mismatches between what the code invites me to do and what it actually does.

# Role
Act simultaneously as senior staff engineer, skeptical first-time API consumer, and adversarial reviewer. No loyalty to the current design. Understand the system deeply enough to challenge it, not merely validate it.

# Scope
Read the codebase in full -- do not sample silently. Build a model of:
- Entry points and real (not documented) execution paths.
- Module boundaries and the contracts between them (explicit and implied).
- Data models, invariants, and where they're actually enforced vs. assumed.
- External surfaces: APIs, CLIs, config, env vars, file formats, network calls.
- The docs/onboarding path a newcomer would actually follow.

Before judging, create a scope inventory:
- Repo type, package managers, major entry points, public surfaces.
- Generated/vendor/build directories excluded and why.
- Test/fixture/example directories read, skimmed, or treated as evidence.
- Commands used to enumerate files and public surfaces.
- Known blind spots.

# Command safety
Prefer read-only inspection and commands that run in local throwaway state. Do not run destructive, publishing, deploy, migration, credential-mutating, network-writing, or external-service-mutating commands unless the repo explicitly documents them as safe local checks and they can be run without secrets. If a useful check is unsafe or needs credentials, mark it BLOCKED and state the exact command you would have run.

# Evidence and severity
Evidence labels:
- CONFIRMED: reproduced, traced end-to-end, or verified against exact code/docs/command output.
- PLAUSIBLE: strong path identified but not fully reproduced.
- BLOCKED: missing dependency, credential, fixture, platform, or unsafe command boundary.
- NOT REPRODUCED: investigated and discarded or contradicted by evidence.

Severity scale:
- Critical: data loss, security exposure, corruption, or impossible core workflow.
- High: wrong public behavior, broken contract, serious safety/DX trap.
- Medium: inconsistent behavior with workaround or limited blast radius.
- Low: clarity, maintainability, naming, or local polish.

# Hunt for (go beyond bugs)
1. Correctness -- logic errors, races, off-by-one, unhandled edges, silently swallowed failures, wrong error propagation.
2. Alternative/unintended paths -- second call? concurrent calls? empty/null/huge input? partial failure mid-op? retries? the "holding it wrong" path?
3. Incoherences -- names that lie about behavior, two modules solving one problem differently, config honored here and ignored there, duplicated sources of truth that can drift, dead code, contradictory defaults.
4. Affordance mismatches -- "I expected to do X this way but can't, or it does something else." Where does the API shape promise a capability the code doesn't deliver? Where is the easy path also the dangerous one?
5. Missing functionality -- things a reasonable user expects (validation, idempotency, cleanup, observability, cancellation, timeouts) but that are absent.
6. Boundary & safety -- leaky abstractions, invariants in the wrong layer, trust in unvalidated input crossing a boundary; injection, path traversal, unbounded growth, resource leaks, missing authz, exposed secrets -- only where real. For security findings, include source -> trust boundary -> sink -> exploit/failure scenario; do not report generic concerns without that chain.
7. Documentation -- README/docstrings/comments that are wrong, stale, or contradict the code; undocumented public behavior, params, errors, or side effects; examples that wouldn't run; missing "why" behind non-obvious decisions.
8. Developer experience -- can a newcomer build, run, test, and debug from the docs alone? Confusing errors, silent misconfig, missing types/CI/tests, setup footguns, high-friction workflows.

# Method (adversarial, then verify)
- Per area, state how it SHOULD behave, then read to confirm or refute. Flag every expectation-vs-reality gap.
- Trace the top critical paths end-to-end, quoting the lines that matter. Check every doc example/command against the code when safe.
- Every finding needs a concrete scenario: specific inputs/state -> the wrong or surprising result. No vague "could be improved."
- Try to disprove each finding first; discard findings that don't survive scrutiny.
- If this overlaps a docs/process audit, keep only findings where codebase structure or implementation evidence adds unique value; otherwise cross-reference the likely audit area.

# Output
Write full report -> docs/audits/codebase-audit-<YYYY-MM-DD>.md. Create dir if missing. Leave uncommitted (maintainer owns git).
Every finding = stable ID within this report (C1, C2... severity order); a fixing agent cites these.
Sections, top-heavy (summary + map first, detail last):
1. Summary table: ID | severity | area | one-line issue | file:line | evidence label.
2. System map: architecture, real execution paths, key invariants -- so I can check your understanding.
3. Coverage accounting: files/dirs read fully, skimmed, excluded, commands run, blind spots.
4. Findings by hunt category, severity order. Each: ID, file:line, one-line issue, concrete failure/surprise scenario (inputs/state -> wrong result), evidence label, recommended direction.
5. Design tensions: 3-5 deepest structural issues (the approach is wrong, not a line); each with the alternative you'd weigh.
6. Expectation gaps: short "expected X, found Y" list for affordance/docs/DX.
7. What held up: short list of important paths/contracts that survived scrutiny.
8. Open questions: what code alone can't resolve; maintainer answers.
Chat reply = short exec summary only: counts by severity/evidence + top 3-5 findings + report path. Rest lives in file.

Be thorough over brief. Prioritize insight density and specificity over reassurance. Where something is sound, say so once and move on -- spend your effort where it isn't.

fable-audit-docs.txt

/goal Audit this project's documentation as a first-class artifact, exactly as specified below -- checking that it tells the truth about the code, that each reader-facing guide leads with what matters and defers detail, that oversized documents are split so detail has room to breathe, and that architecture is shown as drawn processes rather than prose. Treat the docs as the product a reader actually consumes.

# Role
Act simultaneously as: a docs lead who owns information architecture; a skeptical newcomer with only the docs and a terminal; a returning maintainer six months later hunting for one specific fact; and an autonomous agent that must act using the docs as its only spec. No loyalty to the current structure, file layout, or headings.

# Scope
Read every reader-facing surface in full -- do not sample silently:
- README, docs/**, specs/**/quickstart.md, ADRs/decision records, CONTRIBUTING/onboarding.
- Doc-bearing code: public docstrings, module headers, CLI `--help`, config-file comments, example scripts.
- Every diagram already present. Inspect source and rendered output when the local toolchain makes rendering safe and available; otherwise mark render verification BLOCKED.
Build the current documentation map: which document exists, what it claims to cover, who it's for, and how a reader is expected to find it.

Before judging, classify each document by mode:
- tutorial
- how-to
- reference
- explanation
- ADR/decision record
- runbook/troubleshooting
- generated/reference surface

Apply inverted-pyramid expectations primarily to guides, how-tos, runbooks, and onboarding docs. Judge ADRs by context/decision/consequences, and reference docs by completeness, scanability, and single-source-of-truth discipline.

# Command safety
For accuracy checks, prefer read-only commands and local throwaway examples. Do not run destructive, publishing, deploy, migration, credential-mutating, network-writing, or external-service-mutating commands unless the repo explicitly documents them as safe local checks and they can be run without secrets. If a useful check is unsafe or needs credentials, mark it BLOCKED and state the exact command you would have run.

# Evidence and severity
Evidence labels:
- CONFIRMED: verified against exact code, docs, command output, or rendered artifact.
- PLAUSIBLE: strong documentation/code mismatch identified but not fully reproduced.
- BLOCKED: missing dependency, credential, fixture, renderer, platform, or unsafe command boundary.
- NOT REPRODUCED: investigated and discarded or contradicted by evidence.

Severity scale:
- Critical: docs lead users/agents into data loss, security exposure, broken publication/deploy, or impossible core workflow.
- High: wrong public command/API/config behavior, broken onboarding, or missing contract for a primary surface.
- Medium: misleading structure, stale secondary example, scattered source of truth, or missing troubleshooting with workaround.
- Low: local clarity, naming, navigation, formatting, or polish.

# Hunt for
1. Drift / inaccuracy (primary) -- any claim the code no longer honors: renamed/removed commands, flags, env vars, paths, file formats, defaults; examples that don't run; output samples that no longer match; docs describing behavior the code has since changed. And the inverse: real public behavior, params, errors, side effects, and exit codes that no document mentions.
2. Inverted-pyramid violations -- documents that bury the point. Guides/how-tos/runbooks should open with a one-paragraph "what this is / when you'd reach for it" plus the 20% that answers 80% of questions; reference tables, edge cases, and rationale belong later. Flag docs that front-load setup minutiae or history before the reader learns what the thing even is.
3. Sizing / decomposition -- documents grown large enough that concerns collide and detail can't breathe: recommend the split (which sections become their own documents, what each is named, how they link back). Also the reverse: scattered fragments that should merge, and detail suppressed only because there was no room for it.
4. Architecture shown as drawn process -- places where flow, lifecycle, or component interaction is explained in prose that a diagram would carry far better. Identify the key processes with no diagram, and diagrams that are now stale. Prefer Mermaid (flowchart for control flow, sequence for cross-component calls, stateDiagram for lifecycles, C4/component for structure).
5. Usefulness / audience fit -- does each document serve a real reader task, or does it exist because someone felt obliged? Are the four modes (tutorial / how-to / reference / explanation) mixed into one document to nobody's benefit? Does it answer "why," not just "what"? Can a newcomer get from zero to first success on the docs alone?
6. Coverage -- public surfaces (CLI, API, config, env, formats, exit codes, error taxonomy) with no documentation; missing troubleshooting/runbook; non-obvious design decisions with no ADR.
7. Single source of truth -- the same fact stated in N places that will inevitably drift; pick the canonical home and make the rest link to it. Terminology and naming that shift document to document for the same concept.
8. Findability / navigation -- given a real question, can the reader route to the right document without already knowing where it lives? Missing index/map, orphan documents, dead cross-links.

# Method (verify, don't assert)
- For every accuracy claim, check it against reality when safe: run the example, confirm the flag/command/path exists, diff the sample output. Mark evidence honestly.
- For each drift finding, include: document claim -> source of truth checked -> observed reality -> reader impact.
- For structure findings, state the concrete reader task that the current shape defeats, then the shape that serves it -- no taste-only "would read cleaner."
- Try to disprove each finding first; discard what doesn't survive.
- If this overlaps a codebase/process audit, keep only findings where documentation evidence adds unique value; otherwise cross-reference the likely audit area.

# Output
Write full report -> docs/audits/docs-audit-<YYYY-MM-DD>.md. Create dir if missing. Leave uncommitted (maintainer owns git).
Every finding = stable ID within this report (D1, D2... severity order); a fixing agent cites these.
Sections, top-heavy (summary + map first, detail last) -- practice the pyramid you preach:
1. Summary table: ID | severity | document | one-line issue | evidence label.
2. Doc map: current vs proposed. Proposed tree = purpose + audience per doc + the splits/merges from hunt #3; a maintainer executes it directly.
3. Coverage accounting: documents/surfaces read fully, skimmed, excluded, commands/render checks run, blind spots.
4. Drift verification: each accuracy finding + exact check run or BLOCKED reason + result.
5. Findings by hunt category, severity order. Each: ID, document (file:line or heading), concrete reader scenario it breaks, evidence label, recommended direction.
6. Diagram backlog: processes/architecture needing a picture, value order; for the top 3-5 draft minimal Mermaid skeletons, naming target doc + location.
7. Missing-docs backlog: doc/section/example/diagram needed for full coverage + onboarding; prioritize by unblocking value.
8. What held up: short list of important docs or routes that already lead with the truth.
9. Open questions: maintainer-only.
Chat reply = short exec summary only: counts by severity/evidence + top 3-5 findings + report path. Rest lives in file.

Thorough over brief. Spend effort where the docs mislead, bury, or go silent; one line where they already lead with the truth.

fable-audit-process.txt

/goal Perform a process-level audit of this codebase's end-to-end workflows -- not a line-by-line code review, but an examination of whether the processes the product promises actually compose into complete, walkable journeys. Find holes, dead ends, missing transitions, and steps where a user or agent gets stranded.

# Role
Act as a product-minded staff engineer walking every documented journey twice: once as a first-time human user following only the docs, once as an autonomous agent chaining commands via exit codes, structured output, or documented machine-readable surfaces. No loyalty to the current flows.

# Scope
Discover and walk the project's real user/developer/agent workflows. Start from the reader-facing docs and public entry points, then verify against code and command behavior. Include, when present:
- Onboarding: clean checkout/install -> health/preflight -> first successful local run -> required configuration -> green ready state.
- Primary lifecycle: create/import/ingest/initialize -> inspect/list/status -> modify/answer/approve/reject/apply -> terminal or durable state.
- Re-run lifecycle: run the same mutating command twice; re-run after input changes; run out of order; run after partial prior state.
- Output lifecycle: preview/dry-run -> apply/commit/write -> re-apply/idempotency -> cleanup/archive/delete, where supported.
- Publication/export/deploy/release lifecycle, only when safe to exercise locally without external mutation.
- Side processes: discovery/cache/index/state files, generated artifacts, validation, health/doctor/preflight, troubleshooting and recovery.
- Cross-process coherence: enumerate every persistent state a record/artifact/workflow item can occupy and check there is a documented command or API that moves each state forward.

Before judging, create a process coverage inventory:
- Docs, help text, scripts, package commands, CLIs, APIs, and config surfaces used to discover workflows.
- Throwaway workspaces/fixtures created and their initial state.
- Processes fully walked, partially walked, blocked, or intentionally skipped.
- Commands not run because they were unsafe, missing dependencies, or required external services.

# Command safety
Run mutating commands only inside throwaway workspaces, temp directories, or clearly isolated local fixtures. Do not run destructive, publishing, deploy, migration, credential-mutating, network-writing, or external-service-mutating commands against maintainer data or real external systems. If a useful check is unsafe or needs credentials, mark it BLOCKED and state the exact command you would have run.

For concurrency checks, snapshot the relevant workspace files before and after, use throwaway workspaces only, and report whether corruption/state drift was observed. Do not run concurrency tests against maintainer data.

# Evidence and severity
Evidence labels:
- CONFIRMED: reproduced through an exact command sequence or verified from persisted state/output.
- PLAUSIBLE: traced in code/docs but not fully reproduced.
- BLOCKED: missing dependency, credential, fixture, platform, external service, or unsafe command boundary.
- NOT REPRODUCED: investigated and discarded or contradicted by evidence.

Severity scale:
- Critical: data loss, state corruption, unsafe publication/export/deploy, or impossible core workflow.
- High: user/agent stranded in a primary process, broken documented journey, wrong exit/structured-output contract for automation.
- Medium: incomplete lifecycle, inconsistent retry/second-call behavior, missing recovery path with workaround.
- Low: confusing docs/help, local ergonomics, naming, or minor process polish.

# Hunt for
- Dead ends: states with no exit command/API, fixable today only by hand-editing state files or private internals.
- Missing processes: steps that README, docs, specs, quickstarts, examples, or help text promise but no command/API implements.
- Re-run/second-call semantics: every mutating command run twice, out of order, and against a half-completed prior run.
- Agent ergonomics: exit-code semantics per flow; can an agent distinguish "my operation failed" from "unrelated warning elsewhere"? Are JSON/structured-output contracts stable? Do help text and actual flags match? Is error output parseable?
- Docs/process drift: walk the documented flows command-by-command against reality.
- Concurrency: two safe local invocations against the same throwaway workspace for workflows that claim or imply shared-state safety.
- Recovery: partial failure, interrupted command, invalid input, missing dependency, corrupt local state, or deleted generated file. Is there a documented recovery path?

# Method
- Build real throwaway workspaces or fixtures. Keep all generated state local and disposable.
- For each process, record: initial state -> command(s)/API calls -> expected transition -> observed transition -> persisted files or external surfaces changed -> exit code/stdout/stderr/structured-output contract.
- Every finding needs the exact command sequence to reproduce and the resulting state/output.
- Try to disprove each finding before reporting; discard what does not survive.
- If this overlaps a codebase/docs audit, keep only findings where end-to-end workflow evidence adds unique value; otherwise cross-reference the likely audit area.

# Output
Write full report -> docs/audits/process-audit-<YYYY-MM-DD>.md. Create dir if missing. Leave uncommitted (maintainer owns git).
Every finding = stable ID within this report (P1, P2... severity order); a fixing agent cites these.
Sections, top-heavy (summary + map first, detail last):
1. Summary table: ID | severity | process | one-line issue | evidence label.
2. Process map: real workflow/state machine (states, transitions, owning command/API); mark dead ends + unreachable states.
3. Process coverage accounting: workflows walked, fixtures used, commands run, commands blocked, blind spots.
4. Gaps/errors by process, severity order. Each: ID, file:line or command sequence, concrete stranded-user scenario, evidence label, recommended direction.
5. Missing-process backlog: command/API/flag/doc needed per documented journey to complete end-to-end; prioritize by unblocking value.
6. What held up: short list of flows or transitions that survived second-call/regression checks.
7. Open questions: maintainer-only.
Chat reply = short exec summary only: counts by severity/evidence + top 3-5 findings + report path. Rest lives in file.

Thorough over brief. Spend effort where flows break; one line where they hold.