Skip to content

docs(process): point corrections at issue-implement 10.6's sweeps - #2094

Merged
jhoffner merged 3 commits into
mainfrom
claude/sharp-goodall-eocnz5
Sep 23, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/sharp-goodall-eocnz5

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

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:

  • an inline factual correction on a spec, which the triage rule exempts from any follow-up: 3
  • a fold or direction change on a spec: 2
  • a docs-polish pass: 3

The procedure that catches echoes already exists: issue-implement step 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 and polish-docs just 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, run issue-implement 10.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

  • Links: all three relative links to issue-implement/SKILL.md resolve.
  • The rule, run on this change: a surface sweep for other restatements of the exemption across docs/contributing, .agents/skills, AGENTS.md and CLAUDE.md found the issue-spec copy, which is why that file is in the diff. The remaining hits only state that corrections cost no round, which this doesn't touch.
  • Process guards: validate-spec-folder and validate-changeset-refs pass.

No changeset: internal process docs (BP-022).

History note

This PR briefly carried a fix for main's broken workforce build. main has since landed its own fix for the same issue, which also stamps the hiring org (FIX-1542). The merge of main takes main'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

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
@vercel

vercel Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 23, 2026 11:40pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 23, 2026 11:40pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 23, 2026 11:40pm UTC

Request Review

Copy link
Copy Markdown
Collaborator Author

CI is red here because main is red. This PR doesn't cause it.

Typecheck & Test, Storybook Build and Kitchen-sink E2E all fail at @flow-state-dev/workforce#build:

src/manifest-sources.ts(199,38): error TS2339: Property 'manifest' does not exist on type 'RowProblem | { manifest: WorkerManifest; }'.
src/seat-hire-capability.ts(251,44): error TS2339: ...

This PR changes three Markdown files. main's own CI failed the same way at ffe2b6e (run 35912438103). Two PRs merged minutes apart collided:

No fix PR exists yet. The patch below mirrors how roster/reload.ts already handles the same return value:

--- 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 main: the workforce build fails with exactly these errors before the patch and passes after it. The workforce suite passes 755/755 with the patch.

No re-run of this PR's checks: a re-run would fail the same way until main carries a fix.


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
@jhoffner jhoffner changed the title docs(process): point corrections at issue-implement 10.6's sweeps docs(process): point corrections at 10.6's sweeps; fix(workforce): unbreak main's build Sep 23, 2026
jhoffner pushed a commit that referenced this pull request Sep 23, 2026
…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
@jhoffner jhoffner changed the title docs(process): point corrections at 10.6's sweeps; fix(workforce): unbreak main's build docs(process): point corrections at issue-implement 10.6's sweeps Sep 23, 2026
@jhoffner
jhoffner marked this pull request as ready for review September 23, 2026 23:56
@jhoffner
jhoffner merged commit 001d38c into main Sep 23, 2026
13 checks passed
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-23T23:58:29.295131Z ad0635f Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

  1. 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 for apps/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.

  2. “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.

  3. epic-spec door — 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.

Open in Web View Automation 

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants