fix(skills): drop the residual-findings record file for real sinks (#1387)

Author: tmchow

.compound-engineering/config.example.yaml

@@ -8,7 +8,7 @@
 
 # --- Artifact root ---
 # Relocate every CE-written artifact folder (solutions, plans, ideation,
-# explainers, residual-review-findings, pulse-reports, dogfood-reports,
+# explainers, pulse-reports, dogfood-reports,
 # feedback-sweep, personas) under one repo-relative root. Unset -> `docs`,
 # byte-identical to today. A configured root becomes the sole location CE reads
 # and writes; CE never falls back to reading `docs/`.

docs/residual-review-findings/feat-ce-explain-skill.md

@@ -73,7 +73,7 @@ Without an explicit pipeline, autonomous runs tend to skip planning, treat revie
 3. `/ce-work` runs in return-to-caller mode so `lfg` keeps the shipping tail. Behavior-changing work must return verification evidence. Missing evidence is retried once, then the run stops rather than shipping blind.
 4. `/ce-simplify-code` runs on the branch diff before review, unless the change is docs-only or roughly under 10 lines.
 5. `/ce-code-review` (`mode:agent`) reports findings. `lfg` applies eligible mechanical fixes and commits them. Review itself does not edit the tree.
-6. Leftover actionable findings, plus any flagged settlement conflicts, become durable as tracker tickets and a committed file under `<root>/residual-review-findings/`. They are not written into the PR body.
+6. Leftover actionable findings, plus any flagged settlement conflicts, become durable as tracker tickets and one run-report comment on the PR. They are not written into the PR body.
 7. `/ce-test-browser` runs in pipeline mode.
 8. `/ce-commit-push-pr mode:pipeline branding:on` commits remaining changes, pushes, and opens a PR when a remote exists, and marks CE provenance.
 9. `/ce-babysit-pr mode:pipeline` watches the open PR: CI repairs via `/ce-debug`, incoming review comments via `/ce-resolve-pr-feedback`, up to three fix rounds by default. Pipeline babysit stops at "CI decided," not "merged."
@@ -115,7 +115,7 @@ If the completed plan explicitly describes separately planned future areas, `lfg
 
 You finish `/ce-brainstorm` on account-level notification mute. The wrap-up offers `lfg`. You invoke `/lfg` (or `/lfg plan with fable`).
 
-`lfg` builds a settled-decisions brief from the brainstorm, invokes `/ce-plan` on the requirements-only artifact, and waits until that file is `implementation-ready` with `execution: code`. Then `/ce-work` implements in return-to-caller mode. Simplify runs. Review reports findings. `lfg` applies the eligible mechanical ones, commits them, and writes the rest into `<root>/residual-review-findings/<branch>.md` plus tracker tickets when a sink exists. Browser tests run. `ce-commit-push-pr` opens a PR. `ce-babysit-pr` watches CI for up to three repair rounds.
+`lfg` builds a settled-decisions brief from the brainstorm, invokes `/ce-plan` on the requirements-only artifact, and waits until that file is `implementation-ready` with `execution: code`. Then `/ce-work` implements in return-to-caller mode. Simplify runs. Review reports findings. `lfg` applies the eligible mechanical ones, commits them, and surfaces the rest as tracker tickets plus one run-report comment on the PR. Browser tests run. `ce-commit-push-pr` opens a PR. `ce-babysit-pr` watches CI for up to three repair rounds.
 
 The run prints `DONE` and a line to run `/ce-babysit-pr <pr-url>` if you want it watched through review toward merge. It does not merge. If the plan named a later area, you may get a handoff offer. Decline it and the session is over.
 
@@ -211,7 +211,7 @@ No. That is the point of the skill, and why it is the wrong tool for in-the-loop
 The pipeline stops. Non-software tasks, requirements-only leftovers, knowledge-work plans, and invalidating settlement conflicts all halt before implementation.
 
 **Where do leftover review findings go?**
-Not into the PR description. They are filed in the project tracker when possible and always written to `<root>/residual-review-findings/<branch-or-head-sha>.md`.
+Not into the PR description. They are filed in the project tracker when possible, and carried in one run-report comment on the PR.
 
 **What happens if there is no `origin`?**
 Local commits only. No push, no PR, no CI watch.

docs/skills/lfg.md

@@ -45,7 +45,7 @@ Wherever this skill asks the user something, use the platform's blocking questio
 
 ## Artifact Root
 
-This skill may record residuals under `<root>/residual-review-findings/` and compound learnings under `<root>/solutions/`. Resolve `<root>` when you first compose a `<root>/` path (per the block below), never before you need it — a scratch-only or no-repo run that touches no `<root>/` path skips resolution entirely.
+This skill may record compound learnings under `<root>/solutions/`. Resolve `<root>` when you first compose a `<root>/` path (per the block below), never before you need it — a scratch-only or no-repo run that touches no `<root>/` path skips resolution entirely.
 
 <!-- ce-docs-root:start -->
 **Resolve the CE artifact root `<root>` before composing any artifact path.**
@@ -255,7 +255,7 @@ If the user chose "Diagnosis only," skip to Phase 4's summary. If they chose "Re
 
 **The goal: land the fix without carrying along anything the user did not offer up — not into a commit, not into a push, not into a PR.** Do not ask whether to open a PR; permission is not the gate. Two independent questions decide the handoff, and neither answer excuses skipping the other. Answer both from the pre-fix scope Phase 3 recorded, checked now rather than inferred from how the branch came to exist. **Fire the action itself** via the platform's skill-invocation primitive — never merely tell the user to type a command.
 
-**1. What may go into the commit — the fix-owned files and nothing else.** The single addition is an artifact this run generated for the handoff itself: when residual handling falls back to `<root>/residual-review-findings/<branch-or-head-sha>.md`, that file ships with the fix by design, so include it in the scope. This is a constraint on whichever skill commits in question 2, never an action of its own; it holds on every route, remote or not. Do not commit here — question 2 owns the single commit.
+**1. What may go into the commit — the fix-owned files and nothing else.** This is a constraint on whichever skill commits in question 2, never an action of its own; it holds on every route, remote or not. Do not commit here — question 2 owns the single commit.
 
 - No fix-owned file carried pre-existing edits: those files are the commit scope. Pass that scope to whichever skill commits.
 - A fix-owned file already carried the user's pre-existing edits: no commit separates them (`ce-commit` groups at file level and never splits a file). Ask (per **Blocking questions**) *before* anything commits: commit that file including their edits, leave the fix uncommitted for them to handle, or stop. Only the first answer continues — the other two end the handoff here, so question 2 does not run and nothing commits; say what was left and why. This is the one handoff question that survives, because every option loses something the agent cannot choose on the user's behalf. Phase 3's confirmation covered *editing* the file, never committing the user's edits along with the fix — do not reuse it to skip this question.

skills/ce-debug/SKILL.md

@@ -35,7 +35,7 @@ To defer, name the invariant the fix would need to satisfy and why no bounded co
 Never write a PR-body section. Never block. Surface it so the human sees it after the run:
 
 - If it maps to an **open review thread**, leave that thread open (and attach the `decision_context` as a reply when a thread reply is in scope).
-- Otherwise, **return it in the `residuals` list** for the caller to place in its single run-report comment. For a bare `ce-debug` invocation with no orchestrator and no PR, file it as a ticket in the project's tracker (detected in Phase 1.4) with enough background to action it standalone; only when no tracker is reachable, fall back to a committed `<root>/residual-review-findings/<branch-or-sha>.md` file (staged with any fix) as the last resort.
+- Otherwise, **return it in the `residuals` list** for the caller to place in its single run-report comment. For a bare `ce-debug` invocation with no orchestrator and no PR, file it as a ticket in the project's tracker (detected in Phase 1.4) with enough background to action it standalone; when no tracker is reachable, return it in the structured result and say plainly that nothing else recorded it.
 
 `decision_context` uses the shape ce-debug already produces: what the failure is, what you found, why it needs a human decision, options + tradeoffs, and your lean.
 

skills/ce-debug/references/pipeline-mode.md

@@ -16,7 +16,7 @@ The goal of this tail is a **PR-ready** fix, not merely a locally green one —
 
 **Review the final fix scope.** Review every non-mechanical fix unless review tooling is unavailable. Run default `ce-code-review` **only when its diff scope is known to be this fix**: the pre-fix tree was clean and you can pass `base:<pre-fix-HEAD>`. Review reads rather than writes, so a base-scoped diff is worth preferring where it is provably the fix; it is the one place the scope may come from a revision rather than the file list. On a pre-existing dirty branch or one with unrelated committed work, standalone review would reach outside the bug scope — instead use the harness's lightweight review tool if it accepts an explicit file scope, else review the fix-owned files manually and record `Code review: targeted manual due to unrelated branch work`. If `ce-code-review` is unavailable on an otherwise fix-only scope, fall back to the harness's lightweight review tool, else one explicit manual diff scan, and state that dedicated review was unavailable.
 
-**Handle residual findings before shipping.** Do not auto-open a PR with unresolved P0/P1 findings, or with findings whose fix needs a product/design decision — ask whether to fix now, accept/defer durably, or stop. Accepted residuals must not live only in the session: if a PR will be opened, pass them as "Known Residuals" context to `ce-commit-push-pr`; on commit-only or stop, prefer filing a ticket per finding in the tracker detected in Phase 1.4 — pick the sink and file it, do not ask which sink to use — with enough background to action it standalone (the finding, why it matters, file:line, severity, a pointer to the review run, and the branch/head SHA so it points at the code even without a PR). Only when no tracker is reachable, write `<root>/residual-review-findings/<branch-or-head-sha>.md`, stage it with the fix, and name the path in the final summary.
+**Handle residual findings before shipping.** Do not auto-open a PR with unresolved P0/P1 findings, or with findings whose fix needs a product/design decision — ask whether to fix now, accept/defer durably, or stop. Accepted residuals must not live only in the session: if a PR will be opened, pass them as "Known Residuals" context to `ce-commit-push-pr`; on commit-only or stop, file a ticket per finding in the tracker detected in Phase 1.4 — pick the sink and file it, do not ask which sink to use — with enough background to action it standalone (the finding, why it matters, file:line, severity, a pointer to the review run, and the branch/head SHA so it points at the code even without a PR). When no tracker is reachable, name the accepted findings in the final summary and say plainly that nothing else recorded them.
 
 **Re-verify after tail edits.** If simplification or review changed code, rerun the bug's regression test and any targeted checks the tail identified. Never proceed to commit or PR with a red tree.
 
@@ -27,7 +27,7 @@ Then append this block below the Debug Summary, before the commit/PR handoff:
 **Scope**: [fix-only branch / base:<pre-fix-HEAD> / fix-owned files only / targeted manual due to unrelated branch work]
 **Simplify**: [ran/skipped + reason]
 **Review**: [ran/skipped/manual + outcome]
-**Residuals**: [none / accepted Known Residuals for PR / filed as tracker tickets / accepted residuals written to <root>/residual-review-findings/<branch-or-head-sha>.md (last resort) / blocked pending user decision]
+**Residuals**: [none / accepted Known Residuals for PR / filed as tracker tickets / stated in this summary only, no tracker reachable / blocked pending user decision]
 **Re-verification**: [checks rerun after tail edits]
 ```
 

skills/ce-debug/references/post-fix-handoff.md

@@ -356,7 +356,7 @@ This rule prevents two failure modes: (1) regressions where a fix didn't actuall
 
 ### Protected Artifacts
 
-During synthesis, discard any finding that recommends deleting or removing a CE pipeline artifact: any file **under** a `plans/`, `solutions/`, `ideation/`, `explainers/`, `residual-review-findings/`, `pulse-reports/`, `dogfood-reports/`, `feedback-sweep/`, or `personas/` directory (or the legacy `brainstorms/` one) **whose immediate parent is the artifact root**. The artifact root is a directory named `docs` — the default, and where unmigrated legacy artifacts stay even after a project sets `docs_root` — or the configured `docs_root` when this run resolved it. Matching by that parent covers nested category files (`solutions/<category>/foo.md`) while leaving a same-named directory elsewhere — a skill's own `references/personas/` prompt assets, whose parent is `references` — as ordinary code whose deletion finding stands. A review that never resolved a configured root still protects the `docs`-parented tree (default and legacy); a configured-root artifact seen by such a run is the one honest gap.
+During synthesis, discard any finding that recommends deleting or removing a CE pipeline artifact: any file **under** a `plans/`, `solutions/`, `ideation/`, `explainers/`, `pulse-reports/`, `dogfood-reports/`, `feedback-sweep/`, or `personas/` directory (or the legacy `brainstorms/` one) **whose immediate parent is the artifact root**. The artifact root is a directory named `docs` — the default, and where unmigrated legacy artifacts stay even after a project sets `docs_root` — or the configured `docs_root` when this run resolved it. Matching by that parent covers nested category files (`solutions/<category>/foo.md`) while leaving a same-named directory elsewhere — a skill's own `references/personas/` prompt assets, whose parent is `references` — as ordinary code whose deletion finding stands. A review that never resolved a configured root still protects the `docs`-parented tree (default and legacy); a configured-root artifact seen by such a run is the one honest gap.
 
 ## Phase 5: Next Action — Terminal Question
 

skills/ce-doc-review/references/synthesis-and-presentation.md

@@ -8,7 +8,7 @@
 
 # --- Artifact root ---
 # Relocate every CE-written artifact folder (solutions, plans, ideation,
-# explainers, residual-review-findings, pulse-reports, dogfood-reports,
+# explainers, pulse-reports, dogfood-reports,
 # feedback-sweep, personas) under one repo-relative root. Unset -> `docs`,
 # byte-identical to today. A configured root becomes the sole location CE reads
 # and writes; CE never falls back to reading `docs/`.

skills/ce-setup/references/config-template.yaml

@@ -35,7 +35,7 @@ Invocation origin is not observable or relevant: apply the same source-resolutio
 
 ## Artifact Root
 
-This skill discovers plans under `<root>/plans/` and may write review residuals under `<root>/residual-review-findings/`. Resolve `<root>` when you first compose a `<root>/` path (per the block below), never before you need it. A write to `<root>/...` and a read of `<root>/solutions/` both count as composing a `<root>/` path, so either one triggers resolution; only a run that touches no `<root>/` path at all -- a scratch-only or no-repo flow -- skips it; pass the resolved path to any subagent, not the config.
+This skill discovers plans under `<root>/plans/`. Resolve `<root>` when you first compose a `<root>/` path (per the block below), never before you need it. A write to `<root>/...` and a read of `<root>/solutions/` both count as composing a `<root>/` path, so either one triggers resolution; only a run that touches no `<root>/` path at all -- a scratch-only or no-repo flow -- skips it; pass the resolved path to any subagent, not the config.
 
 <!-- ce-docs-root:start -->
 **Resolve the CE artifact root `<root>` before composing any artifact path.**