@warpgogol/forge 0.3.1

package/skills/fo/fo-extract-dna/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: fo-extract-dna
+description: Discover implicit architectural invariants, grill the operator about each, and delegate to fo-idea-create-rfc. After acceptance, append to architecture-dna.md. Use when extracting DNA.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [commands.validateRfc]
+  optional: [paths.invariantsFile]
+triggers: ["extract DNA invariant", "discover architectural invariants", "formalize implicit architectural rules"]
+---
+
+# Extract DNA
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+> **This is a document-only skill.** It produces RFC files in `docs/rfcs/` and, after RFC acceptance, appends entries to `docs/architecture-dna.md` — nothing else. It must never modify, create, or delete source code files in `apps/`, `packages/`, `services/`, or any other directory. It must not run build commands, tests, or validation suites other than `rfc.validate`, `dna.registry.validate`, and `rfc.dna.trace.validate`. Implementation of the RFC's code changes is handled by `fo-idea-implement` after the RFC is accepted.
+
+## Purpose
+
+The codebase contains **implicit architectural invariants** — rules that developers and agents consistently follow but that have never been formally recorded in `ref(forge.yaml bindings.paths.invariantsFile)`. These are DNA candidates waiting to be discovered and formalized.
+
+This skill is the **discovery entry point**: it scans the codebase or listens to the operator's description, identifies patterns that look like stable invariants, grills the operator about each one, and — at agreement — routes through the normal RFC governance pipeline to establish them formally.
+
+**What this skill is NOT:**
+
+- It is not a shortcut that bypasses RFC acceptance. DNA entries are appended to the registry **only after** the establishing RFC is accepted.
+- It is not a bulk scanner that auto-generates DNA. Every candidate requires operator discussion and explicit agreement.
+- It is not a replacement for `fo-idea`. `fo-idea` starts from an operator's idea and routes to RFC/ADR. `fo-extract-dna` starts from **codebase patterns** or **operator-described conventions** and routes to RFC with a DNA-establishment focus.
+
+## Process
+
+### 1. Identify the discovery mode
+
+The operator may trigger this skill in one of two modes:
+
+- **Codebase scan mode** — "find implicit DNA in the codebase", "what invariants exist but aren't recorded", "scan for architectural patterns". The skill scans the codebase to discover candidates.
+- **Convention description mode** — the operator describes a convention they follow ("we always do X", "components must never do Y", "all Z goes through W"). The skill evaluates whether this is a DNA-grade invariant.
+
+If the operator's request is ambiguous, ask using `ask_user_question`:
+
+> "Should I scan the codebase for implicit invariants, or do you have a specific convention in mind to evaluate?"
+
+### 2. Read the existing DNA registry
+
+Before proposing any candidate, read `ref(forge.yaml bindings.paths.invariantsFile)` in full. Record:
+
+- All existing `DNA-N` ids and their titles (to avoid duplicates).
+- The next available `DNA-N` number (max existing + 1).
+- Which invariants are marked "Foundational invariant (pre-RFC)" vs "Established by RFC-XXXX".
+- Which invariants have been "Reclassified to feature".
+
+Also read the RFC template (`os/rfc/rfc-0000-template.md` inside `@warpgogol/forge`) to understand the `satisfies` field and the "DNA-N established by this RFC" marker pattern.
+
+### 3. Discover DNA candidates
+
+#### 3a. Codebase scan mode
+
+Scan the codebase for patterns that **look like stable invariants but are not yet recorded**. Look for:
+
+- **Structural conventions** — directory layouts, file naming, import boundaries that are consistently followed across `apps/*` and `packages/*`.
+- **Code patterns** — repeated type signatures, consistent error handling shapes, uniform export patterns across packages.
+- **Enforcement gaps** — conventions that have a lint/check command but no DNA entry documenting the invariant.
+- **Cross-workspace contracts** — interfaces or schemas shared between packages that are treated as stable but never formalized.
+- **Negative space** — things that are **never done** (e.g. "no app imports from another app" before it was recorded as an invariant).
+
+For each candidate, check:
+
+1. Is this already covered by an existing DNA-N? If yes, skip.
+2. Is this a **stable invariant** (not a temporary convention or migration-period rule)?
+3. Is this **enforceable** — could a Site OS command check it, or is it a documentation-only rule?
+4. Is this **cross-workspace** (applies to multiple apps/packages, not just one)?
+
+Present candidates as a numbered list with a one-line summary each. Do not propose more than 5 candidates in one batch — the operator needs to discuss each.
+
+#### 3b. Convention description mode
+
+Take the operator's description and evaluate it against the DNA criteria:
+
+- Is the convention **stable** (followed consistently, not in flux)?
+- Is it **cross-workspace** (not local to one package/app)?
+- Does it **warrant DNA status** (permanent, not a feature or product decision)?
+- Is it **enforceable** (can a command verify it)?
+- Is it already covered by an existing DNA-N?
+
+If the convention is local, temporary, or a product decision, explain why it is not DNA-grade and suggest an ADR instead.
+
+### 4. Grill each candidate
+
+For each DNA candidate that the operator agrees to pursue, invoke the `/grilling` skill to stress-test it. The grilling examines:
+
+- **Formulation** — is the invariant stated precisely enough to be checkable? Vague formulations like "code should be clean" are not DNA-grade.
+- **Scope** — is this truly cross-workspace, or is it local to one package/app? Local invariants are ADRs, not DNA.
+- **Enforcement** — what Site OS command would enforce this? If no command exists and none is planned, is this really an invariant or just a convention?
+- **Stability** — is this a temporary rule during a migration? DNA invariants are permanent until superseded by another RFC.
+- **Overlap** — does this overlap with or contradict an existing DNA-N? If it extends or refines an existing one, the RFC should amend the original, not create a parallel entry.
+- **Cost of violation** — what breaks if this invariant is violated? If nothing breaks, it is not an invariant.
+- **Agent clarity** — will an AI agent understand this invariant from the DNA entry alone, without reading the RFC? DNA entries are referenced by agents who may not read the full RFC.
+
+Address every concern the grilling raises by adjusting the formulation, scope, or enforcement plan. Do not proceed to RFC creation until the grilling is satisfied with the candidate.
+
+### 5. Present the DNA candidate summary
+
+After grilling, present a structured summary for each candidate:
+
+```
+## DNA Candidate: DNA-<N> · <Title>
+
+**Formulation:** <one-sentence invariant statement, present tense>
+**Scope:** workspace | package
+**Enforcement:** <Site OS command name> or "documentation-only (no command)"
+**Established by:** RFC-XXXX (to be created)
+**Cost of violation:** <what breaks>
+**Related DNA:** <existing DNA-N that this extends, refines, or complements>
+**Grilling verdict:** passed | adjusted | rejected
+```
+
+Ask the operator to confirm or adjust using `ask_user_question`. Do not proceed to RFC creation until the operator explicitly confirms each candidate.
+
+### 6. Delegate to fo-idea-create-rfc
+
+For each confirmed DNA candidate, invoke `/fo-idea-create-rfc` **inline** with the following specifics:
+
+- **title** — the DNA candidate title (imperative sentence).
+- **kind** — `architecture` (DNA-establishing RFCs are always architecture kind).
+- **scope** — `workspace` (DNA invariants are cross-workspace by definition).
+- **satisfies** — leave empty; this RFC **establishes** a new DNA, it does not satisfy an existing one.
+- **In the RFC body**, ensure the "Architectural fit" section contains the canonical marker:
+
+  ```
+  DNA-<N> established by this RFC.
+  ```
+
+  This marker is what `dna.registry.validate` (DNA-REG-03 rule) scans for. Without it, the registry guard will not flag the missing entry.
+
+- **In the "Design" section**, include the proposed DNA registry entry text:
+
+  ```markdown
+  ## DNA-<N> · <Title>
+
+  <One-paragraph invariant description. Present tense, stating the rule as fact.>
+  Enforced by `<command.name>`. Established by RFC-XXXX.
+  ```
+
+  If the invariant is foundational (pre-RFC, already followed but never recorded), use:
+
+  ```markdown
+  Foundational invariant (pre-RFC). Enforced by `<command.name>`.
+  ```
+
+  If no command enforces it yet, the RFC must either:
+  - Propose a new command (making this a command-kind RFC in addition to architecture), or
+  - Explicitly state that enforcement is documentation-only and explain why that is acceptable for this invariant.
+
+Let the creation skill run fully — it will grill, create the file, fill all sections, validate, and report. Do not duplicate its work.
+
+### 7. Report after RFC creation
+
+After the RFC is created, present:
+
+```
+## DNA Extraction Summary
+
+### Candidates discovered: <N>
+### Candidates confirmed: <M>
+### RFCs created: <K>
+
+| # | DNA ID | Title | RFC | Status |
+| --- | --- | --- | --- | --- |
+| 1 | DNA-<N> | <title> | RFC-XXXX | draft |
+
+### Next steps
+- Human architecture review for each RFC draft (status may not change before acceptance).
+- After acceptance: run /fo-extract-dna --register to append DNA entries to `ref(forge.yaml bindings.paths.invariantsFile)`.
+```
+
+**Do not append to `ref(forge.yaml bindings.paths.invariantsFile)` while the RFC is in `draft` status.** The DNA registry entry is added only after the RFC is accepted.
+
+### 8. Post-acceptance registration (separate invocation)
+
+When the operator invokes this skill with `--register` (or says "register DNA", "append DNA", "the RFC was accepted"), perform the registration step:
+
+1. **Verify RFC status** — read the RFC frontmatter. If `status` is not `accepted` or `implemented`, stop with:
+
+   > "RFC-XXXX is `draft`. DNA entries may only be appended to the registry after the RFC is accepted. Run the skill again after architecture review."
+
+2. **Read the current registry** — parse `ref(forge.yaml bindings.paths.invariantsFile)` to find the max DNA-N number and confirm the new DNA-N is not already present.
+
+3. **Append the entry** — add the `## DNA-<N> · <Title>` block at the **bottom** of `ref(forge.yaml bindings.paths.invariantsFile)`, using the text from the RFC's Design section. The entry must include:
+   - The invariant description (present tense, as fact).
+   - `Enforced by \`<command>\`.` (if a command exists or is proposed).
+   - `Established by RFC-XXXX.` (the accepting RFC id).
+
+4. **Validate** — run:
+
+   ```sh
+   ref(forge.yaml bindings.commands.validateRfc) --dna.registry.validate --json
+   ```
+
+   Fix any violations. Common issues:
+   - DNA-REG-01: gap in numbering (entries must be contiguous from 1).
+   - DNA-REG-02: citation points to a non-existent RFC.
+   - DNA-REG-03: RFC says "DNA-N established by this RFC" but registry has no entry (this should now be resolved).
+   - DNA-REG-05: enforcer command is not registered or not pipelined.
+
+5. **Run DNA trace validation** — run:
+
+   ```sh
+   ref(forge.yaml bindings.commands.validateRfc) --dna.trace.validate --json
+   ```
+
+   This verifies the bidirectional trace between the new DNA entry and the RFC's `satisfies` field.
+
+6. **Commit** — stage only `ref(forge.yaml bindings.paths.invariantsFile)` and commit:
+
+   ```txt
+   dna: register DNA-<N> <short title>
+
+   Append DNA-<N> (<title>) to the canonical registry, established by RFC-XXXX.
+   ```
+
+   Stage only `ref(forge.yaml bindings.paths.invariantsFile)` — do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+
+7. **Report**:
+
+   ```
+   DNA-<N> registered in `ref(forge.yaml bindings.paths.invariantsFile)`
+   Established by: RFC-XXXX
+   Enforced by: <command> (or: documentation-only)
+   dna.registry.validate: pass
+   rfc.dna.trace.validate: pass
+   ```
+
+## Constraints
+
+- **Document-only. This skill must never modify, create, or delete source code files.** It must not touch files in `apps/`, `packages/`, `services/`, `tools/`, `scripts/`, or any other source directory. The only files this skill may produce or modify are RFC files in `docs/rfcs/` (via the delegated `fo-idea-create-rfc` skill) and `docs/architecture-dna.md` (during the post-acceptance registration step). If you feel the urge to "quickly implement the enforcer command while I'm here" — stop. That is not this skill's job.
+- **No bypass of RFC acceptance.** DNA entries are appended to `ref(forge.yaml bindings.paths.invariantsFile)` only after the establishing RFC is `accepted` or `implemented`. The skill must verify RFC status before appending. Draft RFCs do not register DNA.
+- **Grilling is mandatory for every candidate.** Do not skip step 4 — every DNA candidate must survive grilling before an RFC is created. The operator's verbal agreement is necessary but not sufficient; the grilling may reveal formulation, scope, or enforcement problems that the operator had not considered.
+- **Operator confirmation is mandatory before RFC creation.** Do not create an RFC for a candidate the operator has not explicitly confirmed. Use `ask_user_question` in step 5.
+- **One RFC per DNA candidate.** If multiple candidates are confirmed, each gets its own RFC. Do not bundle multiple DNA invariants into a single RFC — each invariant must be independently reviewable, acceptable, and supersedeable.
+- **Do not append to `ref(forge.yaml bindings.paths.invariantsFile)` directly during RFC creation.** The registration step (step 8) is a separate invocation, performed after the RFC is accepted. This separation preserves the human review gate.
+- **Do not renumber or delete existing DNA entries.** The registry header says "Agents MUST NOT delete or renumber items; add new entries only at the bottom." This is a non-negotiable rule from `ref(forge.yaml bindings.paths.invariantsFile)`.
+- **Do not create invariant entries for features or product decisions.** Invariants are architectural rules. Features are governed by RFCs but recorded as features. If a candidate is a feature, suggest an RFC without an invariant entry.
+- **Do not create DNA entries for local conventions.** If a convention is local to one package or one app, it is an ADR, not DNA. Route to `fo-idea-create-adr` instead.
+- **Commit only your own files.** Stage only the files this skill produces or modifies — RFC files, `ref(forge.yaml bindings.paths.invariantsFile)`, and nothing else. Do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+- **The canonical marker phrase is load-bearing.** The RFC body must contain exactly `DNA-<N> established by this RFC` (with the correct number) so that `dna.registry.validate` DNA-REG-03 rule can detect it. Do not paraphrase this phrase.

package/skills/fo/fo-fix/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: fo-fix
+description: Iterative fix workflow for AI-generated work. Calls fo-review if needed, applies findings, runs scoped typecheck, commits, and delegates doc updates to fo-doc-audit.
+invocation: user
+category: fo
+concerns: code-mutation
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [commands.typecheck]
+  optional: [commands.test, paths.invariantsFile]
+triggers: ["fix issues from review", "apply review findings and fix", "iterative fix workflow for code"]
+---
+
+# fo-fix
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+Turn a review into corrected code and a green build, then commit. Run in the session where the AI-generated work already lives.
+
+This skill also handles two related fix scenarios:
+
+- **Bug diagnosis** — when the operator reports a bug, regression, or performance issue that requires systematic diagnosis before fixing. See `bug-diagnosis.md` for the 6-phase diagnosis loop (build feedback loop → reproduce → hypothesise → instrument → fix + regression test → cleanup + post-mortem).
+- **Merge conflict resolution** — when an in-progress git merge or rebase has conflicts. See "Merge conflict resolution" below.
+
+## Preconditions
+
+- The artifact (code, docs, etc.) must be present in the current session or workspace.
+- There must be enough context to apply fixes without guessing.
+- For bug diagnosis: the operator has reported a specific symptom (broken, throwing, failing, slow).
+
+## Process
+
+### 1. Check for an existing review
+
+Scan the current session for evidence of a review:
+
+- A persisted review report in `docs/reviews/code/**/*.md` (written by `/fo-review`).
+- A previous `/fo-review` invocation or its output in the current session — look for axis sections like `### Axis A — Structural correctness`, `### Axis B — DNA alignment`, etc.
+- Markdown sections like `[Critical errors]`, `[Warnings / architectural notes]`, or `[Concrete refactor]` (legacy format, still supported).
+- A user statement such as "fix the issues from the review".
+
+If no review is found, run `/fo-review` (or execute its process inline) on the artifact, wait for the review output, and use that as the fix list.
+
+### 2. Apply fixes
+
+Use the review findings as the fix list. The verdict is **not** a stop signal — even an `Approved` review (legacy or lax criteria) may contain findings that must be fixed. Read every axis section and process every finding, regardless of what the verdict line says.
+
+Process findings by axis severity:
+
+1. **Verdict Rejected** — the change has a fundamental flaw (DNA violation, backward compatibility layer, storage policy bypass). Fix all failures before anything else.
+2. **Axis B / D / E failures** — DNA alignment, forward-only compliance, and agent-facing clarity are hard failures. Fix these next. Do not skip without explicit user approval.
+3. **Axis A / C / F / G findings** — structural correctness, ecosystem fit, pragmatism, and blind spots. Fix **all** findings, including cosmetic ones. Do not skip or downgrade a finding because it is "minor" or "cosmetic" — if the reviewer flagged it, it gets fixed.
+4. **Spec compliance gaps** — missing or partial requirements from the original spec. Fix in order of importance.
+
+**No discretionary skipping.** Every finding in the review report must be addressed with a code change. If a finding is truly a false positive, the agent MUST explain why in the session output and get explicit user approval before skipping — but the default is to fix, not to skip.
+
+If the review used the legacy format (`[Critical errors]`, `[Warnings]`, `[Concrete refactor]`), map: Critical → priority 1, Warnings → priority 2, Refactor → priority 3.
+
+For each finding:
+
+- If it includes a concrete line range or code snippet, apply the change directly.
+- If it is ambiguous, ask the user before changing.
+- Do not delete or weaken existing tests without explicit direction.
+- Prefer minimal upstream fixes over downstream workarounds.
+
+After applying fixes, update any tests that should cover the change, then run the relevant package tests before the full build when that saves time.
+
+### 3. Run scoped typecheck verification
+
+**MUST NOT run root `root build` or `turbo run build`.** These commands build every workspace in the monorepo and are prohibitively expensive for iterative fix workflows. See root AGENTS.md §Build verification discipline.
+
+Before running verification, classify the changes made in step 2:
+
+- **Code changes** — any modification to executable source: `.ts`, `.tsx`, `.js`, `.mjs`, `.cjs`, `.astro`, `.json`, `.jsonc`, `.yaml`, `.yml`, `.css`, `.scss`, `.html`, `.vue`, `.svelte`, `.py`, `.go`, `.rs`, or any file that is imported/resolved at build time.
+- **Comment-only changes** — changes inside `// ...`, `/* ... */`, `<!-- ... -->`, or `# ...` without any change to the surrounding executable code.
+- **Documentation-only changes** — changes confined to `.md` files (including `AGENTS.md`, `README.md`, RFC files, ADR files, `docs/**`) that are not imported as code or rendered by the build.
+
+If **all** changes are comment-only or documentation-only (no code changes whatsoever), **skip verification** and note in the session output:
+
+> "Сборка пропущена: изменения затрагивают только комментарии или документацию, исполняемый код не изменён."
+
+Otherwise, determine which workspaces were touched by the fixes in step 2 and run scoped typecheck verification for each:
+
+- **For each touched `apps/*` workspace:**
+
+  ```sh
+  pnpm --filter <app-name> exec astro check
+  ```
+
+- **For each touched `packages/*` workspace:**
+
+  ```sh
+  pnpm --filter <package-name> run build:check
+  ```
+
+  (For packages, `build:check` is `tsc --noEmit` — a lightweight typecheck, not a full build.)
+
+If a workspace cannot be determined from the diff, ask the operator which workspace to verify.
+
+All scoped checks must pass. If any fails:
+
+- Read the error output and identify the root cause.
+- Fix the cause, not the symptom.
+- Re-run the failing check.
+- Repeat until all scoped checks pass.
+
+### 4. Commit the fixes
+
+Stage and commit the changes with a descriptive message.
+
+```text
+git add ...
+git commit -m "fix(scope): ..."
+```
+
+Do not commit secrets, API keys, or unrelated changes.
+
+### 5. Compass header update (fo-compass-annotate)
+
+If the fix touched any source files (`.ts`, `.astro`, `.js`, `.mjs`, `.css`), invoke the `fo-compass-annotate` skill via the `skill` tool with `--changed` flag to update Compass headers (MODULE_CONTRACT, CHANGE_SUMMARY) on changed files. Wait for it to complete.
+
+If no source files were touched, skip this step.
+
+### 6. Documentation audit (fo-doc-audit)
+
+This step is **always** performed — it is not optional and must not be skipped.
+
+Invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces (AGENTS.md, README, Compass XML, `ref(forge.yaml bindings.paths.invariantsFile)`, templates, generated artifacts, COMMANDS.md/PACKAGE_GRAPH.md), applies needed updates, and commits them separately. Wait for it to complete.
+
+If `fo-doc-audit` reports that no updates are needed, state this explicitly and move on — the check itself is the mandatory part, not the outcome.
+
+## Merge conflict resolution
+
+When invoked to resolve an in-progress git merge or rebase conflict:
+
+1. **See the current state** of the merge/rebase. Check git history and the conflicting files.
+2. **Find the primary sources** for each conflict. Understand why each change was made and what the original intent was. Read commit messages, check PRs, check original issues/tickets.
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+4. **Documentation audit.** Invoke `fo-doc-audit` via the `skill` tool. It analyzes the merge changes, checks all documentation surfaces, applies needed updates, and commits them. If no updates are needed, it states this explicitly.
+5. **Run automated checks.** Discover the project's automated checks and run them — typically typecheck, then tests, then format. Fix anything the merge broke. Follow the scoped verification rules in step 3 above.
+6. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.
+
+## Completion criteria
+
+- The review findings were all addressed with code changes. No finding was skipped without explicit user approval for each individual skip.
+- Root `root build` / `turbo run build` was **not** run.
+- Scoped typecheck verification (`astro check` for touched apps, `tsc --noEmit` for touched packages) passes for every touched workspace, **or** verification was skipped because all changes were comment-only or documentation-only.
+- At least one fix commit exists on the branch.
+- `fo-doc-audit` was invoked and documentation surfaces were checked; any doc changes are committed separately.
+- For bug diagnosis: the 6-phase loop in `bug-diagnosis.md` was followed, or phases skipped were explicitly justified.
+- For merge conflicts: all hunks resolved, automated checks pass, merge/rebase completed.

package/skills/fo/fo-fix/bug-diagnosis.md

@@ -0,0 +1,128 @@
+# Bug Diagnosis Loop
+
+A discipline for hard bugs and performance regressions. Use when fixing a bug that requires systematic diagnosis — not for straightforward review findings that point directly at the fix.
+
+Skip phases only when explicitly justified.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with a structured script so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100x, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the operator for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** that you have **already run at least once**, and that is:
+
+- **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed.
+- **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate).
+- **Fast** — seconds, not minutes.
+- **Agent-runnable** — you can run it unattended.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+A minimal repro shrinks the hypothesis space in Phase 3 and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+## Phase 3 — Hypothesise
+
+Generate **3-5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the operator before testing.** They often have domain knowledge that re-ranks instantly. Don't block on it — proceed with your ranking if the operator is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow, a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for a potential `fo-architecture` investigation.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- Original repro no longer reproduces (re-run the Phase 1 loop)
+- Regression test passes (or absence of seam is documented)
+- All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+- **AI and human documentation updated** — analyze whether the bug fix altered a contract, convention, workflow, or pattern that ecosystem developers should know about. If so, update the relevant `AGENTS.md` or `README` files before committing. If no updates are needed, state this explicitly.
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to `fo-architecture` with the specifics. Make the recommendation **after** the fix is in, not before.

package/skills/fo/fo-handoff/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: fo-handoff
+description: Compact the current conversation into a handoff document for another agent to pick up. Saves to OS temp directory, not the workspace.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+triggers: ["create a handoff document", "compact conversation for next agent", "prepare handoff for another agent"]
+---
+
+# fo-handoff
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS — not the current workspace.
+
+## Process
+
+### 1. Gather context
+
+Review the current conversation to identify:
+
+- What was being worked on
+- What was completed
+- What remains to be done
+- Any blockers, open questions, or decisions pending
+
+### 2. Write the handoff document
+
+Include:
+
+- **Suggested skills** — which skills the next agent should invoke and why.
+- **References to existing artifacts** — specs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead of duplicating content.
+- **Current state** — what the codebase looks like now, what's uncommitted, what's in progress.
+- **Next steps** — concrete, actionable items the next agent should pick up.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+### 3. Save
+
+Save to the OS temporary directory — not the current workspace. On Windows, use `$env:TEMP`. On macOS/Linux, use `/tmp`.
+
+If the operator passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+
+### 4. Report
+
+Tell the operator the absolute path of the handoff document and suggest opening a fresh session that references it. Report in `aiLanguage`.
+
+## Constraints
+
+- **Do not save to the workspace.** The handoff document goes to the OS temp directory.
+- **Do not duplicate existing artifacts.** Reference them by path or URL.
+- **Redact sensitive information.** API keys, passwords, PII.
+- **Commit only your own files.** This skill does not commit anything — the handoff doc is in the temp directory. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.