Repository navigation
docs(process): catch sibling systems before they're built; trim restated guidance - #3884
Conversation
Five lessons from FIX-2058, where one user-visible concept (a task waits on a person) was built twice and then glued together: - tenet 2: a decision that accepts a second way to do one job names the shared type both write and the next likely variant, or it isn't ready for a gate; asking-for-decisions points at it - analysis: the next-variant test under Other shapes - analysis guardrails + adhd scoring: an alternative dropped only for contradicting a decision in the same epic goes back to the user - reuse-review: sibling specs' Adds count as existing; worked example 3 now teaches the holds[] case instead of "two holds are fine" - review coherence lens + cross-spec-review: glue code that keeps two of our own mechanisms apart is a finding against the model Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
The always-loaded files restated rules whose full text lives elsewhere. Each now keeps the one-line rule and links the canonical home: - asking for sign-off (asking-for-decisions.md), in both files - release notes (BP-022 + release-notes-workflow.md), in AGENTS.md - artifacts a human reads (writing-for-humans.md), in AGENTS.md - the Codex reviewer rule and workflow scripts (orchestration.md) - the skill table: one line per skill; each skill's frontmatter holds the full description No rule changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
orchestration.md and the lifecycle and POC skills each restated the same rules. Kept the canonical statement and replaced the copies with links: - spec POC vs settlement comparison and variant rules: spec-poc skill - where a spec POC's record lives: spec-poc "Publishing it" - when a settlement earns a draft PR: settle-claim Step 5 - settle-claim's restated trigger: orchestration.md "When it fires" - local PR-watch mechanics (Monitor vs CronCreate, signals, cursor): watch-pr; orchestration.md keeps the coordinator's obligations - spec-review budget and PR-feedback cap rationale in issue-lifecycle and epic-lifecycle: orchestration.md; the skills keep their mechanics - drops the "considered and deferred: feedback router" history note No gate, budget, cap or merge rule changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
issue-spec Step 6.5, BP-040, BP-041, pr-reviewer-guidance §3 and the
spec template each restated rules canonical in orchestration.md
("Spec review", "When it fires") or asking-for-decisions.md (the six
parts, the three-ask ceiling, filtering is sorting). They keep the
operational steps and link the rule. issue-spec's companion-skill
bullets for settle-claim and adhd shrink to when-to-reach-for-it.
No rule changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
from: fsd-claude CI red: Cause: the test depends on the clock. It hard-codes "the daily one runs before next Monday's":
So every week, from Sunday 11:30 UTC (after Sunday's daily run) until Monday 09:00 UTC, the next weekly run comes before the next daily one, and the hard-coded order is wrong. This run started at 18:29 UTC on a Sunday. No fix exists yet. I'm not widening this docs PR to include one. Proposed patch: assert soonest-first from the values the test already checks, instead of a fixed order: // Soonest first, whatever their keys.
const due = listed.schedules.map((s) => Date.parse(s.nextRunAt!));
expect(due).toEqual([...due].sort((a, b) => a - b));The loop below it still pins each A re-run inside the window fails the same way, so I'll re-run this job once after Monday 09:00 UTC. Generated by Claude Code |
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: Direction is right — net −172 lines, budgets/POC/watch-pr/sign-off prose correctly delegated to orchestration.md, spec-poc, watch-pr, and asking-for-decisions.md. That is the cleaner maintenance shape this repo already uses elsewhere.
Where the approach overshot: The PR fixes duplication by deleting copies, but the FIX-2058 / sibling-reuse lesson is added in several skills at once (philosophy tenet, analysis next-variant test, reuse-review sibling search + §3 case study, cross-spec-review glue, review coherence glue). Agents now learn one invariant in ~5 places instead of one. A simpler alternative would have been:
- Two canonical homes —
philosophy.md(why) +orchestration.md→ Compose existing pieces (epic sibling specs count as “existing”; glue/reconciler = missing shared abstraction). - One worked example — keep FIX-2058 in
reuse-review§3 (or linkspecs/epics/FIX-2058/DECISIONS.mdER-8) without replacing the old generic hold/release table. - Pointers elsewhere —
analysis,cross-spec-review,review,adhdget one-line “apply compose-existing-pieces / reuse-review” links instead of restating tests.
What I would not revert: Removing the orchestration POC comparison table (→ spec-poc), watch-pr mechanics essay (→ skill), deferred feedback-router note, and lifecycle budget rewrites — all good layering.
Skipped (optional / follow-up): CLAUDE.md skill-table trigger column; AGENTS.md vs CLAUDE.md sign-off dedupe; audit-coherence alignment with the new glue smell.
No runtime/code risk. Happy to approve after a small canonicalization pass, but mergeable as-is if you accept the distributed-doc tradeoff.
Sent by Cursor Automation: Review For Best Approach
Name siblings-count-as-existing, glue as a missing abstraction, and the next-variant test once, in orchestration.md -> Compose existing pieces. analysis, reuse-review, cross-spec-review and review point at it instead of each restating its slice. issue-lifecycle's round-cap reference gets a real link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MeLMkkdahHfyQKi5XXTFT2
|
from: fsd-claude CI red: Cause: two merges crossed. FIX-2162 ( No fix exists yet (no open PR touches
Re-running won't help, because the failure is deterministic until Generated by Claude Code |


Problem. Epic FIX-2058 built "a task waits on a person" twice. A suspension and a held question each had their own row field, Inbox source, answer route, deadline, cancel and crash recovery. A third PR then added glue to keep the two from colliding: a reconciler clause, a sweep rule, and refusals written on both sides. The amendment in #3881 fixed the design with one
holds[]list. But every review step passed the split:reuse-reviewcompared each spec only againstmain, never against its siblings.Separately, our guidance has gotten bloated, with the same rules restated in many places.
What this does. Process docs only, no product code. 17 files, +146 / −318.
A. Five lessons, each a sentence or two, in one canonical home each:
philosophy.md, tenet 2, plus one line inasking-for-decisions.md). A decision that accepts a second way to do one job must name the type both ways write, and the next likely variant.analysis→ Other shapes. If adding the next variant would copy more than one piece, the shared abstraction is missing.analysisguardrails,adhdscoring). It isn't "considered and dropped".reuse-reviewcounts sibling specs' Adds as existing. Worked example Infer resource state types in projections and add portable projection resource schema options #3, which taught that separate holds are fine, is replaced by theholds[]case.reviewcoherence lens,cross-spec-review).B. Streamlining. Rules stated in several places now live in one home, and the other copies are links:
asking-for-decisions.mdrelease-notes-workflow.mdspec-poc,settle-claim,orchestration.mdwatch-prorchestration.mdCLAUDE.md's skill table is now one line per skill, and some history notes were removed.CLAUDE.mdgoes from 37.9 KB to 31.8 KB.What's asked of you. Review the five additions, since tenet 2 is a philosophy change. Then decide on the proposals below.
Proposals left out (each changes a rule, so it's yours):
orchestration.md→ "Epics already running when this rule landed", a one-time migration note, once no epic from before the closure rule is still running.CLAUDE.md's full mirror of the universal BPs with a one-line index plus links. This needs the mirror policy inbest-practices.mdchanged.issue-lifecycleandepic-wakeboth cite. Today there are two prose copies.Parts worth reviewing closely
docs/philosophy.md, about line 110). It's the one change at philosophy altitude.issue-lifecycleandepic-lifecycle, the largest trims. I checked that every "never" and gate rule they dropped still exists in its canonical home: merge policy not waived by convergence, the coordinator dispatches, Codex as reviewer, private-package changesets, and approvals and merges inwatch-pr.Behavior preserved. No gate, approval, merge, "never", security, secrets or Linear-channel rule changed. No workflow script changed, and no heading or anchor was renamed.
Verification
node scripts/check-retired-terms.mjs: PASS, and--controlPASS.node goals/vocabulary/one-word-per-thing/sweep.mjs: PASS, and--controlOK.node scripts/check-isolation-coordinate.mjs: OK.node scripts/validate-spec-folder.mjs: clear.node .agents/workflows/verify.mjs: 332/332..md: 323 links. The only misses are pre-existing placeholder links in the example bodies ofspec-template.mdandpr-reviewer-guidance.md.validate-side-chain-vocabulary.mjs, which needspnpm install. CI covers it.No changeset: process docs only, so no published package changes.
Generated by Claude Code