Repository navigation
docs(process): point corrections at issue-implement 10.6's sweeps - #2094
Conversation
Cycle 15 of the cycle ledger (FIX-1208) found eight findings where a correction was right where it landed and another surface kept saying the old thing. They came through three doors: inline factual corrections on a spec (exempt from the re-draft), folds, and a docs-polish pass. The obligation all three need already exists as issue-implement 10.6's word and surface sweeps, so this adds pointers to it rather than new rule text: - orchestration.md, spec-review triage: after the cheap exception - issue-spec, the same triage restatement (found by running the sweep on this change) - polish-docs, Verify Corrections still cost no review round. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
CI is red here because
This PR changes three Markdown files.
No fix PR exists yet. The patch below mirrors how --- a/packages/workforce/src/manifest-sources.ts
+++ b/packages/workforce/src/manifest-sources.ts
@@ -196,6 +196,7 @@
if ("problem" in parsed) continue;
const record = hiredSeatManifest(orgId, parsed.row);
+ if ("problem" in record) continue;
if (!declared.has(record.manifest.id)) {
--- a/packages/workforce/src/seat-hire-capability.ts
+++ b/packages/workforce/src/seat-hire-capability.ts
@@ -248,6 +248,9 @@
const record = hiredSeatManifest(orgId, row);
+ if ("problem" in record) {
+ throw new Error(`"${address}" could not be hired: ${record.problem}.`);
+ }
const [seat] = hireWorkforce([record.manifest], {Verified on a clean checkout of No re-run of this PR's checks: a re-run would fail the same way until Generated by Claude Code |
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
…call sites main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools), merged minutes later, added two call sites that read `.manifest` without narrowing, so @flow-state-dev/workforce no longer compiles. Both now handle the problem case the way roster/reload.ts already does: - manifest-sources: a row owned by another org is skipped when listing seats, alongside the unparseable-row skip on the line above. - seat-hire-capability: the hire refuses with the row's reason. Verified: the workforce build fails on main with exactly CI's four TS2339 errors and passes with this change; workforce 755/755; pnpm typecheck 70/70. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8 (cherry picked from commit db41f92) Ported from PR #2094 unchanged, so this spec PR's CI builds while main is red. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
main now carries its own fix for the hiredSeatManifest narrowing (plus the FIX-1542 org stamp); take main's side, which leaves this branch as the process-docs change only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Simplify review
Verdict: The direction is right. Option B from the FIX-1208 / cycle-15 ledger entry — point at issue-implement §10.6, don’t paraphrase a second reconciliation rule — is the cleaner change compared with bolting new prose onto the cheap-exception sentence. This PR is small, docs-only, and matches an existing pattern (canonical procedure in one skill step; entry-point callouts elsewhere). I’m approving; what follows is optional tightening, not a merge block.
Did this go too far?
No, relative to the alternative. A new “re-derive every surface…” clause (ledger option A) would be more complexity and more drift risk. Three callouts look like duplication, but they are three doors (orchestration contract, issue-spec execution, polish-docs verify) — same obligation, different lifecycle. That’s intentional reachability, not a new subsystem.
The one place I’d consider less text, not more:
issue-spec§6.5.1 already tells agents that orchestration’s “Spec review: the bar…” section is canonical (line 535). Repeating the full echo sentence here mirrors orchestration (consistent with how triage is duplicated today) but is the easiest DRY win: a single back-reference (“echo sweeps per orchestration → spec-review triage”) would preserve behavior for agents who only open the skill, with one fewer copy of the obligation sentence to keep in sync.
Cleaner approaches considered
| Approach | Tradeoff |
|---|---|
| This PR (B) | Procedure stays in §10.6 only; callouts add triggers. Best match to ledger recommendation. |
Canonical hub in orchestration.md + named anchor (e.g. “Claim echo sweeps”) |
Slightly clearer navigation than “10.6’s word and surface sweeps” under a heading titled “Completion gate — no code comment left silent”. Optional follow-up in issue-implement, not required for this PR. |
| Split §10.6 (e.g. 10.6.1 “Reconcile prose”) | Better grep/navigation for non–PR-feedback lifecycles; larger change, out of scope here. |
| New BP or shared markdown fragment | Poor fit: long procedural content already lives in a skill step; BPs stay short. |
Nits (uncertain they should change)
-
polish-docs→issue-implement§10.6 — Understandable reuse of the canonical procedure, but §10.6 is framed as a PR-feedback completion gate (comment enumeration, Step 5C exception forapps/docs/). A polish pass is the authorized docs edit; one clarifying phrase (“you are already the docs pass — converge hits here; don’t treat Step 5C as ‘dispatch writer/editor’”) might reduce mis-application. I’m not sure that belongs in this PR vs a tiny §10.6 lead-in tweak. -
“Any correction, inline or folded” — Fold-in work is already supposed to go through 6.5.2 re-draft. Bundling folded + inline in one breath is defensible (ledger counted fold echoes too) but blurs “cheap exception” vs “direction re-draft”. If agents over-sweep on large folds, narrowing to inline factual fixes only would be lighter — would change my mind if post-merge compliance data shows spec authors running full §10.6 on one-line typos.
-
epic-specdoor — Ledger noted epic fold echoes; this PR doesn’t add a pointer there. Reasonable scope cut; flag only if you want symmetry across all spec lifecycles.
Performance / code quality subagent pass
N/A for runtime. Operational cost is intentional agent time when corrections happen — by design.
Summary: Ship as-is. If you want one follow-up simplification with near-zero product risk, shorten the issue-spec duplicate to a pointer at orchestration; everything else is polish.
Sent by Cursor Automation: Review For Best Approach
| **Settle on the loop, not on the assertion.** A claim asserted *once* — however confidently, however wrong it sounds — is ordinary triage: answer it, fold it, or drop it with a pointer to the code. The trigger is the **second** pass: the claim came back after being answered, or the spec has already flipped on it, or two rounds reached opposite conclusions. That repetition is the signal prose has failed on it, and it's the one case where another round of argument is predictably wasted. Fire then, and not before — POC-ing every assertion would replace a two-round review with a queue of experiments, which costs more than the debate did. | ||
|
|
||
| **The default is Note, and the burden of proof is on folding.** If you can't name which decision card or which part of the approach changes, it isn't spec-level. The one cheap exception: genuine factual corrections and broken references get fixed inline without ceremony — they don't move the design, so they don't cost a round. | ||
| **The default is Note, and the burden of proof is on folding.** If you can't name which decision card or which part of the approach changes, it isn't spec-level. The one cheap exception: genuine factual corrections and broken references get fixed inline without ceremony — they don't move the design, so they don't cost a round. Any correction, inline or folded, still owes its echoes: before the push, run [`issue-implement`](../issue-implement/SKILL.md) 10.6's word and surface sweeps over every claim you corrected, and report both. |
There was a problem hiding this comment.
Simplify nit: §6.5 already sends readers to orchestration as canonical for this bar (line 535). You could replace this full sentence with a short back-pointer (“…including echo sweeps per orchestration → spec-review triage”) and keep a single copy of the obligation text in orchestration.md. Optional — the mirror matches today’s issue-spec/orchestration duplication pattern.
| - Re-read moved/merged pages once as a reader to confirm the rearrangement flows. | ||
|
|
||
| Where the pass changed what a page asserts, not only its wording, sweep every claim you corrected: | ||
| run [`issue-implement`](../issue-implement/SKILL.md) 10.6's word and surface sweeps over the docs |
There was a problem hiding this comment.
Linking to §10.6 is the right reuse, but that section opens as a PR-feedback gate and later says not to hand-edit apps/docs/ during implement feedback (Step 5C). For polish-docs, you are the docs pass — worth one clause that hits found in docs/READMEs get converged in this PR (not deferred to 5C). Uncertain this belongs in this PR vs a one-line framing tweak in §10.6 for non-implement lifecycles.
| it's a note. Genuine factual corrections and broken references are the one cheap | ||
| exception: fix them inline without ceremony (they don't move the design, so they don't | ||
| cost a round). | ||
| cost a round). Any correction, inline or folded, still owes its echoes: before the push, run |
There was a problem hiding this comment.
“Inline or folded” reaches fold echoes (ledger intent) but sits on the paragraph about the cheap exception. If you ever see agents treating every fold like a repo-wide grep obligation on top of 6.5.2, consider scoping the pointer to inline factual corrections only — I’d wait for evidence before changing.


The problem
When a spec or doc gets a fact corrected, the correction usually lands correctly, but another surface that restated the old fact keeps saying it. The next review round finds that echo. FIX-1208's lessons entry (cycle 15, #2059) counted eight of these, arriving through three routes:
The procedure that catches echoes already exists:
issue-implementstep 10.6 defines a word sweep (grep the old claim everywhere) and a surface sweep (visit every summary, table and README that restates it), and requires both to be reported. Spec review andpolish-docsjust never point at it.What this changes
This is option B from #2059, which the owner chose. It adds pointers to 10.6 and no new rule text:
docs/contributing/orchestration.md, spec-review triage: after the cheap-exception sentence, "Any correction, inline or folded, still owes its echoes: before the push, runissue-implement10.6's word and surface sweeps over every claim you corrected, and report both.".agents/skills/issue-spec/SKILL.md: the same sentence where the skill restates that triage rule..agents/skills/polish-docs/SKILL.md, Verify: a short paragraph asking for the same sweeps whenever a pass changes what a page asserts.Corrections still cost no review round.
How it was checked
issue-implement/SKILL.mdresolve.docs/contributing,.agents/skills,AGENTS.mdandCLAUDE.mdfound theissue-speccopy, which is why that file is in the diff. The remaining hits only state that corrections cost no round, which this doesn't touch.validate-spec-folderandvalidate-changeset-refspass.No changeset: internal process docs (BP-022).
History note
This PR briefly carried a fix for
main's broken workforce build.mainhas since landed its own fix for the same issue, which also stamps the hiring org (FIX-1542). The merge ofmaintakesmain's version, so this PR no longer touches any code.What's asked of you
Nothing urgent. This is a docs-only process change and is ready to merge whenever you want it.
🤖 Generated with Claude Code
https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8