Menu
This skill should be used when exploring requirements and approaches through collaborative dialogue before planning implementation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | brainstorm |
| description | This skill should be used when exploring requirements and approaches through collaborative dialogue before planning implementation. |
You are the exploration orchestrator. Whether entered via /go (default route) โ /brainstorm or direct /brainstorm:
/plan (default) or /one-shot (when requirements are already clear). Do not read their SKILL.md and improvise.plugins/soleur/lib/harness.ts โ Grok uses /plan, /one-shot; Claude uses Skill tool (soleur:plan, soleur:one-shot).See plugins/soleur/lib/workflow-fidelity.ts (BRAINSTORM_CHILD_SKILLS) and go.md Step 2.1 (go-post-route block).
Note: The current year is 2026. Use this when dating brainstorm documents.
Brainstorming helps answer WHAT to build through collaborative dialogue. It precedes the soleur:plan skill, which answers HOW to build it.
Process knowledge: Load the brainstorm-techniques skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
<feature_description> #$ARGUMENTS </feature_description>
If the feature description above is empty, ask the user: "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
Do not proceed until you have a feature description from the user.
Load project conventions:
# Load project conventions
if [[ -f "CLAUDE.md" ]]; then
cat CLAUDE.md
fi
Read CLAUDE.md if it exists - apply project conventions during brainstorming.
Branch safety check (defense-in-depth): Run git branch --show-current. If the result is main or master, and knowledge-base/ exists, create the worktree immediately (pulling Phase 3 forward) so that dialogue and file writes happen on a feature branch. Derive the feature name from the feature description (kebab-case). Run SOLEUR_SKILL_NAME=brainstorm SOLEUR_EXPECTED_DURATION_MIN=60 ${CLAUDE_PLUGIN_ROOT:-./plugins/soleur}/skills/git-worktree/scripts/worktree-manager.sh feature <name> (env vars wire a session lease that blocks sibling cleanup-merged from reaping this worktree), then cd .worktrees/feat-<name>, then immediately run bash ${CLAUDE_PLUGIN_ROOT:-../../plugins/soleur}/skills/git-worktree/scripts/worktree-manager.sh draft-pr from inside the worktree to push the branch and open a draft PR before any further work. Set WORKTREE_CREATED_EARLY=true so Phase 3 skips worktree creation AND skips the duplicate draft-pr step. If knowledge-base/ does not exist, abort with: "Error: brainstorm cannot run on main/master without knowledge-base/. Checkout a feature branch first." This check fires in all modes as defense-in-depth alongside PreToolUse hooks -- it fires even if hooks are unavailable (e.g., in CI). Why push immediately: an unpushed feature branch can be wiped by a concurrent session's cleanup-merged sweep โ the Phase 3 race-window warning applies the same way at Phase 0, just with a longer exposure (Phase 0.1, 0.25, 0.5, 1.0, 1.1, 1.2, and 2 all happen before Phase 3 today). See knowledge-base/project/learnings/2026-04-21-concurrent-cleanup-merged-wipes-active-worktree.md.
Pre-worktree premise probe (stale "doesn't exist" / "blocked by" / "deferred from" / "after PR #N" claims). BEFORE pulling Phase 3 forward, if the feature description contains a #N reference AND gh issue view <N> --json body body contains literal text matching does not yet exist OR deferred from #?\d+ OR blocked by #?\d+ OR temporal-precondition framings (after|when|gated on|pending) PR #?\d+ ?(merges|lands|ships|is merged)?, probe each cited reference: try gh pr view <ref> --json state,mergedAt first (the cited #N is often a PR not an issue, and mergedAt is the load-bearing field โ a PR can be CLOSED-not-merged), fall back to gh issue view <ref> --json state,closedByPullRequestsReferences on PR-lookup failure; AND git show origin/main:<named-artifact> (NOT bare-repo ls) for any artifact path cited in the issue body. The bare repo's working tree can lag origin/main and produce false-negative "missing" results for files that exist at the canonical ref โ propagating into a wrong-premise re-framing. If git show fails, defer the artifact-existence check until after the worktree is created and re-grep from inside it. If ALL cited blockers are CLOSED / referenced PRs are MERGED and ALL named artifacts exist, the premise is stale โ re-frame with the user BEFORE creating the worktree. Why: #3987 stale-claim case; #4078 bare-root false-negative for cited 2026-05-19-pr-h-trust-tier-external-classes-brainstorm.md; #4319 temporal-precondition miss where "After PR #4289 merges" framing wasn't matched by the status-verb regex and PR #4289 had already merged 2026-05-22T08:07Z by brainstorm time. See knowledge-base/project/learnings/2026-05-18-premise-validation-and-multi-clause-predicate-reading.md, knowledge-base/project/learnings/2026-05-21-brainstorm-premise-verification-call-site-granularity-and-adr-mutability.md, and knowledge-base/project/learnings/2026-05-22-brainstorm-precondition-pr-merge-gate.md. Forward-companion canary: the regex above is backward-looking; a forward reference to an unlinked companion ("Companion PR (creates X): to be linked", "seeded under a separate PR") is a distinct canary it misses โ the companion is filed to land in parallel and on a fast repo routinely merges BEFORE the brainstorm runs. When an issue frames work as "create X" AND cites a not-yet-linked companion that creates X, run git show main:<X> + gh pr list --state all -L 200 --search "<X>" before accepting the greenfield framing; if X exists, the real scope is the remainder the issue tracks, not X. Why: #5754 โ register domain-model.md already existed via companion PR #5773 (merged the prior day); greenfield framing would have re-built it. See knowledge-base/project/learnings/2026-07-01-brainstorm-companion-pr-to-be-linked-already-merged.md.
Plugin loader constraint: Before proposing namespace changes (bare commands, command-to-skill migration), verify plugin loader constraints -- bare namespace commands are not supported, and commands/skills have different frontmatter and argument handling.
Evaluate whether brainstorming is needed based on the feature description.
Clear requirements indicators:
If requirements are already clear: Use AskUserQuestion tool to suggest: "Your requirements seem clear enough to skip brainstorming. How would you like to proceed?"
Options:
skill: soleur:one-shot for full autonomous execution (plan, deepen, implement, review, resolve todos, browser test, feature video, PR). Best for simple, single-session tasks like bug fixes or small improvements.skill: soleur:plan to create a plan before implementingIf one-shot is selected, pass the original feature description (including any issue references) to skill: soleur:one-shot and stop brainstorm execution. Note: this skips brainstorm capture (Phase 3.5), worktree creation (Phase 3), and spec/issue creation (Phase 3.6) -- the one-shot pipeline handles setup through the plan skill.
Per AGENTS.md hr-weigh-every-decision-against-target-user-impact, every brainstorm is unconditionally treated as user-brand-critical before any domain leader is spawned. Per #5175 (operator decision from the #5085 brainstorm): the operator always answered the prior framing question with "all of them," so prompting added friction without ever changing the posture. The user-impact lens is now forced onto every decision by default โ there is no question to ask.
Step 1 โ Set the flag unconditionally (no prompt, no parse). Set USER_BRAND_CRITICAL=true for the rest of the brainstorm session. Do NOT present an AskUserQuestion; do NOT scan the request for trigger keywords. The always-on posture is intentional โ it over-protects (fail-safe direction) rather than risk under-protecting a feature whose impact looks purely technical at first glance.
Step 2 โ Synthesize the ## User-Brand Impact block. Capture a ## User-Brand Impact block so Phase 3.5 can persist it into the brainstorm document for plan-time carry-forward:
$ARGUMENTS (the concrete thing being built, e.g. "the X endpoint", "the Y skill"). This MUST be the real surface, never a static literal โ a concrete artifact keeps plan-time carry-forward and the user-impact-reviewer honest, preventing the always-on default from degrading into a rubber stamp.single-user incident.Then announce: "Tagged as user-brand-critical (auto, per #5175). CPO + CLO + CTO will be spawned in parallel at Phase 0.5 before other specialists. The plan derived from this brainstorm will inherit Brand-survival threshold: single-user incident unless overridden."
Step 3 โ Emit telemetry. Emit rule-application telemetry so the weekly aggregator records that the brainstorm enforcement layer fired (see AGENTS.md hr-weigh-every-decision-against-target-user-impact):
source "$(git rev-parse --show-toplevel)/.claude/hooks/lib/incidents.sh" && \
emit_incident hr-weigh-every-decision-against-target-user-impact applied \
"Every plan/PR touching credentials, auth, data, paym"
The gate now fires on every brainstorm by design (per #5175), so this emit records every application of the rule. Accepted tradeoff: the "fired vs. asked" ratio is now constant (always fired) โ that diagnostic signal was deliberately traded away for zero operator friction. Do NOT delete the emit; the per-application record is still consumed by the weekly aggregator.
Step 4 โ Persist the framing into the brainstorm document. The brainstorm capture in Phase 3.5 MUST include a ## User-Brand Impact section reflecting the synthesized framing (artifact = the feature's named surface, vector = generic, threshold = single-user incident). The plan skill's Phase 2.6 carries this section forward into the plan, so re-authoring at plan time is unnecessary and risks drift.
Why: Triggered by #2887 โ the dev/prd Doppler-config collapse shipped because every prior gate weighed the decision on technical and convenience axes only, and no gate asked what one user's data breach would cost the brand. This is the earliest layer of enforcement for the workflow gate; it pairs with plan Phase 2.6 (template), deepen-plan Phase 4.6 (halt), preflight Check 6 (ship gate), and the user-impact-reviewer conditional agent to close the loop. #5175 made the gate unconditional โ the operator's standing "all of them" answer is encoded as an always-on default, removing the per-brainstorm prompt while preserving (and strengthening) the always-protective posture.
Select an orchestration lane that describes the Phase 0.5 domain-leader breadth. Canonical vocabulary: plugins/soleur/skills/brainstorm/references/brainstorm-domain-config.md ## Lane Inference. Written to spec.md frontmatter at Phase 3.6.
Skip if USER_BRAND_CRITICAL=true from Phase 0.1 โ set LANE=cross-domain and proceed to Phase 0.25 without prompting. Phase 0.1 now sets this unconditionally (per #5175), so the lane is always fixed to cross-domain here; there is no framing prompt to double up on.
Otherwise (vestigial fallback โ under #5175 Phase 0.1 sets USER_BRAND_CRITICAL=true unconditionally in every mode, so the skip above always fires and this block is currently unreachable; retained as the escape hatch for any future per-feature USER_BRAND_CRITICAL override):
Keyword scan the feature description against the ## Lane Inference table.
Pipeline / headless mode detection. If the parent invocation was /soleur:one-shot, /soleur:go --headless, or any non-interactive context (no TTY available, HEADLESS_MODE=true), set LANE=<keyword-inference-result> directly โ fail-closed to cross-domain if no keyword matches. Skip the AskUserQuestion gate. Echo to the operator-facing terminal: Phase 0.4: pipeline mode โ lane=<value> (inferred). Continue.
Interactive mode โ AskUserQuestion. Three presets (the runtime appends auto-Other automatically โ do NOT include "Other" as a fourth preset per the 4-option cap):
"Lane""Phase 0.5 domain-leader breadth. Inferred: <inferred-lane>."(Recommended). Each option's description quotes the Phase 0.5 effect from the canonical table.Resolve response. If the operator picks a preset, set LANE=<picked>. If the operator picks "Other" and the text resolves to a literal lane value, use it. If "Other" does not resolve, fail-closed: LANE=cross-domain AND echo to operator terminal: Phase 0.4: free-text "<text>" did not resolve โ fail-closed to cross-domain. (Visible terminal echo, not just artifact note โ per spec-flow G3.)
Operator-override telemetry note (FR6). When the chosen lane differs from the keyword-inferred default, add a one-line bullet to the brainstorm doc body's ## Lane section: Lane override: inferred=<inferred>, chosen=<chosen>. Also echo to operator terminal so the override is visible immediately (not just on doc re-read).
Domain leaders read knowledge-base/product/roadmap.md as ground truth. If the roadmap's status columns are stale, every domain assessment is unreliable. This step syncs the roadmap with GitHub milestone data before domain leaders are spawned.
Skip if knowledge-base/product/roadmap.md does not exist. Topic ("internal tooling", "CLI infra", "developer-tool", "agent infrastructure") is NOT a skip criterion โ the milestone count check is cheap, and stale roadmap rows surface as Phase 3.6 friction regardless of brainstorm topic. See knowledge-base/project/learnings/2026-05-09-brainstorm-skill-heuristics-substring-match-roadmap-skip-cmo-scope.md.
last_updated frontmatter date./soleur:product-roadmap validate): bash ${CLAUDE_PLUGIN_ROOT:-plugins/soleur}/skills/product-roadmap/scripts/roadmap-reconcile.sh validate. It emits STALE_STATUS / MISSING_ISSUE / EMPTY_MILESTONE verdicts naming each drifted phase + the milestone's live open/closed counts. (This replaces the previous hand-rolled per-milestone gh issue list loop, so detection logic lives in exactly one place.)STALE_STATUS verdict, update that phase's ## Current State count cell to the milestone values the verdict reports. If any CLOSED issue is listed as "Not started", "Stub only", or "In progress", update it to "Done".last_updated frontmatter to today's date only โ a reconcile is an automated write, never a human review, so it must NOT bump last_reviewed (that would silently reset the roadmap's review clock; ADR-094).git add knowledge-base/product/roadmap.md && git commit -m "docs: sync roadmap statuses from GitHub milestones". (Freshening before leaders spawn is a narrow count-sync write, distinct from the report-only validate skill.)Why: In #1745, the CPO assessed KB sharing as premature because "KB API and viewer are not started" โ but both had been shipping for weeks. The stale roadmap caused a domain leader to give incorrect sequencing advice, wasting a brainstorm cycle.
Scan $ARGUMENTS for substrings matching [A-Z]{2,}-[0-9]+ or linear\.app/[^/]+/issue/. If any match:
skill: soleur:linear-fetch, args: "$ARGUMENTS". The skill returns two artifacts: agent_context (the markdown blob + image content blocks, streamed into THIS brainstorm conversation only) and persist_safe_summary (the same text with every uploads.linear.app/* URL redacted to [linear-image: REDACTED]).agent_context for Phase 2 Synthesis and Phase 3 Capture โ when synthesizing or writing the brainstorm doc, you may reference the visual content directly but MUST NOT write any uploads.linear.app URL into the brainstorm file. Use persist_safe_summary for any direct quotation of issue body text in the brainstorm doc.persist_safe_summary (NOT agent_context, NOT $ARGUMENTS) in the leader prompt's context section. Task subagents inherit prompt text only โ they do not receive image content blocks (see knowledge-base/project/learnings/best-practices/2026-05-12-task-subagent-prompt-text-only.md). The leaders' assessment will be text-only-aware; the brainstorm parent retains the visual context for its own synthesis.Phase 0.4 must complete before Phase 0.5 spawns leaders. The two phases are sequential despite Phase 0.5 internally parallelizing leader spawns. If no Linear references match in $ARGUMENTS, Phase 0.4 is a no-op and the brainstorm proceeds directly to Phase 0.5 unchanged.
Assess whether the feature description has implications for specific business domains. Domain leaders participate in brainstorming when their domain is relevant.
Read plugins/soleur/skills/brainstorm/references/brainstorm-domain-config.md now to load the Domain Config table with all 8 domain rows (Marketing, Engineering, Operations, Product, Legal, Sales, Finance, Support). Each row contains: Assessment Question, Leader, Routing Prompt, Options, and Task Prompt.
Emit rule-application telemetry only when the brainstorm scope matches the rule's trigger โ i.e., the feature description proposes a new skill, agent, or user-facing capability. For internal infra/CI brainstorms (where the rule does not apply), skip the emit. The telemetry records rule fires, not gate reached โ emitting on every brainstorm pollutes the rule-fire count and breaks the unused-rule reporter.
source "$(git rev-parse --show-toplevel)/.claude/hooks/lib/incidents.sh" && \
emit_incident hr-new-skills-agents-or-user-facing applied \
"New skills, agents, or user-facing capabilities must"
LANE from Phase 0.4.
LANE=procedural: Skip Phase 0.5 entirely; echo Phase 0.5: skipped (lane=procedural) to the operator terminal so the bypass of 8 potential leaders is visible (per spec-flow G2); proceed to Phase 1.LANE=single-domain: After step 1 selects the relevant-domain set, spawn only the single highest-relevance leader. On tie at highest score, fall back to config declaration order in brainstorm-domain-config.md domain table (first match wins). No AskUserQuestion at this point โ tie-break is deterministic to support pipeline/headless mode.LANE=cross-domain: After step 1, if fewer than 2 domains matched Assessment Questions, expand by adding the next-highest-relevance domain not yet in the set; tie-break by config declaration order; repeat until โฅ2 leaders fire. Echo the expansion: Phase 0.5: cross-domain expansion added <domain> (relevance tied; config-order tie-break) to the operator terminal (per spec-flow G6).USER_BRAND_CRITICAL=true triad override (step 2) wins unconditionally โ the triad is always mandatory when set; LANE shapes any additional leader inclusion only.knowledge-base/project/learnings/2026-05-05-brainstorm-spawn-cpo-cmo-early-on-external-product-trigger.md.{desc} with the feature description. When the feature is anchored on a specific prospect or customer signal, gather verifiable facts about them (headcount, named roles, employment relationship vs. retainer/advisor) BEFORE spawning leaders and thread these facts into every Task Prompt alongside {desc} โ quotes alone admit multiple readings that leaders may resolve confidently in the wrong direction (see knowledge-base/project/learnings/2026-04-27-prospect-anchored-brainstorm-fact-loading.md). If Phase 0.4 fired (Linear references detected and linear-fetch returned a persist_safe_summary), the {desc} substitution MUST use persist_safe_summary in place of the raw $ARGUMENTS โ never the agent_context artifact, never a uploads.linear.app URL. If multiple domains are relevant, spawn them in parallel. Weave each leader's assessment into the brainstorm dialogue alongside repo research findings.brand_survival_threshold and ## Domain Review (carry-forward) sections (detect via gh issue view <N> --json body + grep for plan:.*\.md or by referenced plan path), AskUserQuestion: carry-forward only (reuse plan's leader sign-offs verbatim; user-impact-reviewer at PR review remains the load-bearing gate) vs focused refresh (spawn leaders with prompts narrowly scoped to: does User-Brand Impact still hold under the new scope decision; any code drift since plan date; one new delta this brainstorm introduces; does any inherited transparency/disclosure surface (banner, blast notification, in-product banner) still match THIS PR's audience โ drop if the affected cohort is reachable by a cheaper, more honest channel per knowledge-base/project/learnings/2026-05-12-brainstorm-re-audit-inherited-transparency-surfaces.md). Cap refresh prompts at 250-350 words per agent; forbid sub-agent spawning. See knowledge-base/project/learnings/2026-05-11-bundle-brainstorm-deliberate-revert-and-fixture-source-record.md Pattern 3.Read plugins/soleur/skills/brainstorm/references/brainstorm-brand-workshop.md now for the full Brand Workshop procedure (worktree creation, issue handling, brand-architect handoff, completion message). Follow all steps in the reference file, then STOP -- do not proceed to Phase 1.
Read plugins/soleur/skills/brainstorm/references/brainstorm-validation-workshop.md now for the full Validation Workshop procedure (worktree creation, issue handling, business-validator handoff, completion message). Follow all steps in the reference file, then STOP -- do not proceed to Phase 1.
If the feature description references an external platform, marketplace, or service, WebFetch the URL first before launching any research agents. Classify by: (1) self-service or waitlist? (2) discovery surface or procurement layer? (3) does it accept the product category? (4) what are the per-plan quantitative limits? (number of tasks, storage, API calls, concurrent sessions) (5) does the limit cover the migration/feature scope? (6) if the brainstorm is evaluating the candidate as a replacement for an existing headless/MCP/CLI integration, does the candidate expose a programmatic surface (MCP server, CLI, or HTTP API) that agents can call without a browser? If no, it is a complement for human-led work, not a replacement โ do not spawn agents to design a migration. (7) if the URL points to a third-party Claude Code skill / plugin / vendor-branded repo, run gh api repos/<o>/<r>/contents/<entry>/SKILL.md --jq .content | base64 -d to detect vendor-marketing surface (utm-tagged links, vendor logos, "powered by" footers) injected into agent output. Vendor surface is usually localized to README + repo-scan footers โ share the contamination map with the user before spawning leaders, and price three options (vendor-as-is / lift-with-MIT-attribution / clean-room) rather than two. This 30-second gate prevents spawning agents that analyze a false premise. Why: In #1094, a 9-workflow migration plan was built before discovering the Max plan allows only 3 Cloud scheduled tasks โ a limit only discoverable by attempting to create the 4th task or checking via the RemoteTrigger API. Why (6): #2699 โ Claude Design (GUI-only) would have broken ux-design-lead, /soleur:frontend-design, /soleur:ux-audit, and the Product/UX Gate if treated as a Pencil replacement. Why (7): 2026-05-09 brainstorm of gosprinto/compliance-skills โ utm-tagged Sprinto links inside skill description would have leaked operator prompt context to a third party as a de facto sub-processor; see knowledge-base/project/learnings/2026-05-09-evaluating-vendor-branded-claude-code-skills.md.
If the feature description references named external systems, prior issues, prior brainstorms, or numerical claims (caps, counts, byte budgets), grep existing truth sources (CI report, roadmap, prior brainstorms) for those named entities or claims before launching research agents. Three exit branches: (a) confirmed โ proceed to 1.1; (b) contradiction โ re-scope with the operator and restart 1.0.5 on the revised framing; (c) operator override โ annotate the disagreement in the brainstorm body and proceed. A framing defect caught here is worth more than a full research sprint built on it.
An issue's archaeology โ why the current state exists โ is a claim to VERIFY against the PR that made it, not context to accept. When the feature description explains current state with speculative-causality language ("probably", "almost certainly", "(probable)", "became permanent", "the workaround stuck", "at some point someone", "presumably"), the author is reconstructing, not reporting โ the hedge is the trigger token. Verify BEFORE it bounds the option space: git log -1 --format='%H %ad %s' --date=iso -L <start>,<end>:<path> on the state's own lines, or gh pr list --state all -L 200 --search "<the thing that moved>" โ gh pr view <N> --json title,mergedAt,body. A deliberate decision and an accident have opposite fixes โ the accident framing makes "revert it" read as cleanup when it is actually undoing a working fix, and a PR merged BEFORE the issue was filed settles it. The PR title is the cheapest intent oracle in the repo and is almost never consulted. Why: #6538 โ "web-2 was almost certainly placed in fsn1 as a stock workaround โฆ The workaround became permanent"; PR #6393, merged three days BEFORE the issue was filed, is titled "relocate warm-standby web-2 hel1โfsn1 (cross-DC HA)" with the rationale recorded in both variables.tf and server.tf. The issue's recommended option would have reverted a 3-day-old fix for a repo-wide apply wedge. See knowledge-base/project/learnings/workflow-patterns/2026-07-16-issue-archaeology-is-a-claim-verify-against-the-pr-that-made-the-state.md.
Grep the ADR corpus for the proposed mechanism, not just the cited issue refs. When the feature description names HOW to do something (a frontmatter flip, a new table, a polling cron, a config tier), grep knowledge-base/engineering/architecture/decisions/ for the mechanism's keywords and read any hit's ## Decision + ## Alternatives Considered BEFORE accepting the framing or confirming a design with the operator. An issue is filed without knowledge of what an ADR decided; a mechanism in an ADR's rejected-alternatives table is explicitly-rejected, not unconsidered โ re-scope to "did the ADR leave a gap this still addresses?". Why: #5087 โ operator-confirmed frontmatter tiering matched the exact alternative ADR-053 (#5096) rejected the day before; caught only at deepen-plan. See knowledge-base/project/learnings/2026-06-11-brainstorm-grep-adr-corpus-for-proposed-mechanism-not-just-issue-refs.md. Also verify any cited ADR number โ mechanism mapping before threading it into a subagent/leader prompt โ a number carried from prior prose (e.g. "Anthropic-only = ADR-083") can be wrong (ADR-083 is the scoped strong-model consult; the model policy is ADR-053), and leaders will repeat the wrong citation as a given; git grep "ADR-0NN" main + read the citing text, and cross-check tree-wide before concluding an ADR is absent (a git ls-files glob miss โ non-existence). See knowledge-base/project/learnings/2026-07-04-verify-adr-citation-numbers-before-threading-into-subagent-prompts.md.
When a governing ADR already contains the design, re-verify each deferral trigger against LIVE state โ the "deferred/blocked" label is the most perishable part of an ADR. A same-day ADR may record the full design AND label items deferred/blocked; trusting the label re-derives decided work or re-confirms a status that has since cleared. Read the deferral rationale and re-run the exact check it implies: gh run list --workflow=<apply>.yml if the reason is "pipeline RED"; gh pr list --state all -L 200 --search "<N> in:body,title" for a sibling that shipped an item ("Ref #N" merges leave the issue OPEN with the box unchecked); gh issue view <blocker> --json state,title to confirm the cited blocker is real and open; grep the IaC/source for the true cross-ref (a mis-cited blocker in prose is corrected by the code). Then the brainstorm's job is certify-and-scope, not explore-and-derive. Why: 2026-07-03 #5933 โ ADR-082 (same-day) deferred Item 1 "blocked on #5887 (pipeline RED)", but #5887 was fixed, the apply was green, and Item 3 had already shipped via PR #5945; the blocker was mis-cited (#5887 is a closed CI fix; the real cutover is #5274). See knowledge-base/project/learnings/2026-07-03-brainstorm-re-verify-adr-deferral-triggers-against-live-state.md.
Grading a competitor/vendor claim VERIFIED vs UNSUBSTANTIATED means reading every source the artifact already cites โ a landing page is one source, not the source of truth. When a leader/CMO reports "X is not stated on vendor.com," check whether the artifact you're annotating already links subpages (a /pricing, a docs/blog post) for that exact claim, and read those before grading. Asserting "unsubstantiated" from an incomplete source check is the same defect class as asserting an unverified figure as fact โ just reversed. Why: #6827 โ Cofounder pricing/memory/ownership were graded "not stated on cofounder.co" from a landing-page-only fetch; the existing competitive-intelligence.md table row already linked cofounder.co/pricing + a memory post that stated them verbatim. See knowledge-base/project/learnings/2026-07-22-verify-every-cited-source-and-corrections-must-not-half-sweep.md.
Credential/auth/ToS features โ probe the customer-facing-vs-operator-self-use framing split before accepting a blanket "prohibited." A domain-leader (esp. CLO) PROHIBITED verdict is a verdict on ONE framing under ONE snapshot of vendor terms. Two cheap probes can invert it: (1) is there a narrower actor/scope (operator self-use, single-tenant, BYO-own-credential) that dissolves the fatal clause (credential sharing/pooling/reselling apply to customer-facing, not operator-self-use)? (2) are the cited terms current? Verify external-vendor commercial/ToS terms via live WebFetch of the official source dated to the present โ terms drift and can flip within days. Why: 2026-06-02 #4825 โ a triad PROHIBITED for customer-facing Claude-subscription login flipped to permitted-with-guardrails for operator self-use once the actor narrowed AND Anthropic's June-15-2026 Agent-SDK-credit policy was read live. See knowledge-base/project/learnings/2026-06-02-brainstorm-framing-split-flips-tos-verdict-and-verify-vendor-terms-live.md.
Verify dependency-chain target states when the feature description cites cross-issue actions. Extend the Pre-worktree premise probe above: if the feature description (or referenced parent issue body) names actions like unblock #N, comment on #N to close, closes #N when this lands, or depends on #N closing, run gh issue view <N> --json state,closedByPullRequestsReferences for each cited target. If the target is already CLOSED via a PR whose number is NOT in the current brainstorm's scope, the dependency chain has been satisfied through an independent path โ record in the brainstorm doc's ## Session Errors so PR-body authors don't add stale cross-issue actions. See knowledge-base/project/learnings/workflow-patterns/2026-05-20-brainstorm-ladder-collapse-and-dependency-chain-staleness.md.
A soak-gated / "required-on-signal" tracker item is not scopeable until its trigger fires โ and an issue-body obstacle is usually a property of the author's imagined approach, not the goal. When the feature description is a multi-item tracker: (1) for any item gated on a soak/observation window ("if X stays non-zero after a one-week soak", "required-on-signal", "close only if zero residual"), verify the gating event's merge/clock date (gh pr view <N> --json mergedAt) โ if the window has not elapsed, scope ONLY the independently-actionable sibling items and surface the gated one as "not yet actionable" via AskUserQuestion, rather than spinning up worktree+leaders for work whose trigger has not fired; (2) when an item's body asserts an obstacle ("needs a push-shaped payload", "expands blast radius"), grep the consuming helper's ACTUAL signature before accepting it โ the obstacle is often specific to the heavyweight approach the author imagined and dissolves under a lighter one (e.g. syncWorkspace pulls live default-branch HEAD itself, so no synthetic push payload is needed). See knowledge-base/project/learnings/2026-06-29-brainstorm-soak-gated-tracker-item-and-grep-helper-sig-before-accepting-obstacle.md.
A stale deferral's recorded REASON can be wrong while its VERDICT is right โ re-derive the mechanism before reversing it. Falsifying a deferral's stated rationale (the cited token IS in Doppler; the "unresolvable" id DOES resolve) does NOT establish that its verdict was wrong โ the prior decider may have been right for a reason they never wrote down. Premise-probing correctly flags such an artifact as stale, and that is exactly what makes it dangerous: the probe's success manufactures confidence to reverse a correct decision. Before acting on the re-frame, re-derive the verdict's MECHANISM with the actual call (terraform plan, the real API request under the real token) โ not the citation. Corollary: an id resolved via endpoint A is NOT evidence a Terraform data source can read it (the data source may hit endpoint B under a different scope), and a data-source failure is a whole-root outage on every future apply, not a local one. Why: #6285 โ the deferral's two stated blockers were both false, yet its rejection of data "sentry_team" was still correct: the IaC token has no team:read, so the data source 403s at PLAN time and would wedge every apply-sentry-infra run. See knowledge-base/project/learnings/2026-07-15-sentry-event-frequency-threshold-unreachable-and-data-source-scope-403.md.
"Resource X is exhausted, so guard operation Y" โ trace whether Y actually CONSUMES X at the moment it runs, before scoping the guard. A replace/swap/rotate-shaped operation frees its own unit before taking one and is therefore net-zero on the resource it appears to exhaust โ the guard belongs on the additive path, if anywhere (and there it is usually redundant, since an additive create fails cleanly with zero blast radius). Also check WHICH vendor error code the cited incident actually threw: an exhaustion code (account-wide quota, fixed by a vendor form) and an availability code (per-DC stock, fixed by not pinning a DC) are different counters with different fixes, and a guard on the wrong one returns green while the failure happens. "No headroom" is intuitively alarming and reliably mis-aimed. Why: #6453 โ a free_slots == 0 preflight would have failed every recreate for no reason (terraform -replace destroys first, freeing its slot, then creates), and the cited incident #6393 threw resource_unavailable (hel1 DC stock), not resource_limit_exceeded (the cap); the wrong model survived the issue author, the CPO, and the platform-strategist. See knowledge-base/project/learnings/2026-07-15-replace-shaped-ops-are-net-zero-on-the-resource-they-exhaust.md.
An issue claiming an artifact "has no consumer" is a claim about a CONTRACT, and a contract has two sides. Before scoping a new consumer, run two cheap probes: (1) grep -rn "<artifact-path>" --include="*.ts" --include="*.yml" . for existing readers; (2) read the producer's append instruction and the consumer's selection predicate side by side. An artifact with two live readers can still never drain if the producer writes below the section the consumer reads, or if the consumer selects on ABSENCE of a field most rows lack. Why: #6827 โ seo-refresh-queue.md had two consumers; flagged rows landed below ## Refresh Schedule while the consumer read only ยง1.x/ยง2.2/ยง2.1, and its "no generated_date" predicate made ยง1.1 Homepage permanently eligible. See knowledge-base/project/learnings/2026-07-22-no-consumer-claim-is-a-producer-consumer-contract-mismatch.md.
Pre-research: check existing KB artifacts first. Before spawning any agents, run one local check for prior brainstorms and specs matching the feature's topic keywords:
find knowledge-base/project/brainstorms knowledge-base/project/specs knowledge-base/project/learnings \
-maxdepth 3 -type f -iname "*<keyword>*" 2>/dev/null | head -n 20
If prior artifacts exist, read them and frame the research agent prompts as "given these prior decisions, what's changed and what gaps remain?" rather than "research this topic cold." Why: In the 2026-04-17 BYOK usage dashboard brainstorm, the prior 2026-04-10-byok-cost-tracking-brainstorm.md and specs/feat-byok-cost-tracking/spec.md had already decided scope; agents rediscovered them mid-session instead of building on them. See knowledge-base/project/learnings/2026-04-17-brainstorm-verify-existing-artifacts-and-mount-sites.md. Use -type f to avoid false positives from empty spec directories left by prior worktree-manager.sh feature runs that bailed before writing spec.md. Run the find from inside the worktree (after Phase 0/Phase 3 worktree creation) โ the bare-repo root checkout can drift from origin/main and surface paths that don't exist at the worktree's revision, wasting research-agent prompt budget on summarize-a-missing-file instructions. Same rule for git ls-files, grep -r, and any other pre-spawn premise-validation queries whose result will be passed verbatim into a Phase 0.5 / Phase 1.1 subagent prompt โ the bare root's index can lag main's HEAD, producing ghost-absent files that propagate into the subagent prompt as load-bearing false-negative assertions. See knowledge-base/project/learnings/2026-05-15-brainstorm-leader-research-sequencing-and-prior-art-cwd.md and knowledge-base/project/learnings/2026-05-19-bare-repo-grep-and-subagent-infra-claim-verification.md.
Write-mostly artifact diagnosis. When the prior-art grep surfaces an existing ledger/queue/backlog/inventory that matches the claimed gap, check whether it has any closure markers (resolution status, linked closing issue, or gh issue list --state closed -L 200 --search "<topic>" hits). An artifact with zero closures over months is a falsifiable signal that automation producing more entries will compound the backlog, not the knowledge โ reframe the brainstorm to ship the lifecycle/closure prereq first and let 60-day closure evidence decide whether the production loop is worth building. Why: 2026-05-12 #2723 tech-debt-tracker brainstorm โ issue framed as "no persistent ledger" but knowledge-base/project/learnings/technical-debt/ already had 11 entries with structured frontmatter and zero closures; the triad reframed to lifecycle prereq (#2723) + deferred scheduled scanner (#3650) with ALL-must-hold re-evaluation criteria, avoiding a CI-report-nobody-reads outcome. See knowledge-base/project/learnings/2026-05-12-brainstorm-write-mostly-artifact-diagnosis-and-lifecycle-prereq.md. For "make X legible/visible/surfaced" features specifically: existence of the source is insufficient โ measure its production rate (count rows past the ledger's header marker; gh pr list --search "head:<branch-shape>" --state all -L 200). A source that exists but has produced ~0 entries means the display surface renders empty; the real prereq is fixing the producer, not building the viewer. AND when copy says "your X got smarter/better", grep the producer for tenant scope (workspace_id, WHERE tenant) โ if it only writes global/shared artifacts, possessive per-tenant framing is a deceptive-implication risk; reframe to product-level. Why: 2026-07-06 #6039 โ promotion-log had 0 rows, 0 self-healing/auto-* PRs ever, and improvement is global-harness-only; re-scoped to an operator dogfood + deferred the founder surface (#6102). See knowledge-base/project/learnings/2026-07-06-measure-data-production-rate-before-scoping-a-visibility-surface.md.
"Channel nobody reads / ~0% resolution" is a claim to root-cause, not a write-only-sink framing to accept. When an issue reports an escalation/notification channel is ignored and names its harvesting component as the likely single point of failure, verify the harvester actually RUNS and DELIVERS before designing around the assumed failure: (1) gh run list -R <owning-repo> โ the harvester's schedule often lives in a SEPARATE (frequently private) repo the public repo only references, so run-history must be pulled from the owner, not grepped locally; (2) gh issue list -R <repo> --json assignees โ assignees=[] on notification-style issues is a silent delivery failure (the artifact exists, nobody is pinged); (3) a partially-draining backlog (many closed, oldest rotting) is UNTRIAGED, not dead โ the rot concentrates in structurally-dead classes (chores the actor cannot/will not do) mixed flat with genuine emergencies. A channel that delivers-but-is-ignored has a different fix (triage + delivery + de-pollute + aging) than one that never fires. Why: #6769 โ action-required "~0% resolution / operator-digest never ran" was disproved in one check: the digest ran weekly (green), but digests #1โ#7 had empty assignees (never notified) and Section 4 rendered a flat --json title,url list where a 131-day chore looked identical to a P0. See knowledge-base/project/learnings/2026-07-22-channel-nobody-reads-root-cause-before-write-only-sink-framing.md.
An "advisory-first, promote later per the precedent" framing is a claim to MEASURE before it sets the new gate's posture. When an issue cites a prior gate as calibration precedent, verify the precedent's promotion actually happened โ the author is citing the intent they remember, not the outcome: (1) grep -rl "<scanner>" .github/workflows/ โ if it returns nothing, the "precedent" is a skill script, not a CI gate, and there was never an advisory stream to promote; (2) gh issue view <calibration-issue> --json state,createdAt,comments โ compare age against the stated window and count ORGANIC findings (a window open past its deadline with only ship-day comments + a triage bot produced nothing); (3) ask whether ANY advisory gate in this repo was ever promoted to blocking โ if zero-for-N, born-blocking is the only mechanism with a track record, and "advisory now, blocking later" is the option that reliably ships a warning stream with no reader and no expiry. A gate that cannot be scoped precisely enough to block is evidence the detector is wrong, not evidence it needs a calibration window. Why: #6517 โ tier1-scan.ts is in zero workflows and calibration issue #4270 sat OPEN at 56 days against a stated 2-week window with 0 organic findings, while the arm that did ship blocking (#4646) was born blocking. See knowledge-base/project/learnings/2026-07-16-advisory-first-precedent-is-a-claim-to-measure-and-a-coordinate-citation-carries-no-claim.md.
Also check sibling/closed issues for prior framings of the same mechanism. When the feature_description references #N with a parent (Parent: #M in the body or an umbrella issue), read the parent's child list AND run gh issue list --state all -L 200 --search "<core-mechanism-keywords>" to surface deferred or closed prior framings. Why: 2026-05-11 #2720 brainstorm โ the issue was a re-framing of #421 (deferred Layer 2 of self-healing-workflow); without this check, the brainstorm would have produced a parallel spec orphaning #421. See knowledge-base/project/learnings/2026-05-11-brainstorm-parallel-domain-and-research-fan-out-and-duplicate-issue-discovery.md. When the inciting event is a vendor pricing/model/terms change, additionally grep OPEN issues for deferred work whose re-evaluation criteria name that event class (gh issue list --state open -L 200 --search "deferred <pricing|model|vendor-keyword>") โ deferred issues encode prior leader consensus plus re-open criteria, and the brainstorm's job may be certifying the trigger fired, not re-deriving the decision (2026-06-10: #3791's "pricing change" trigger sat dormant through the Fable 5 release). When the operator explicitly overturns a recorded deferral/validator verdict instead of certifying its trigger: state in the brainstorm which conditions are satisfied vs. overridden and why, comment the partial override on the deferred issue (keep it OPEN for the un-overridden remainder), and inherit its captured "if/when built" decisions verbatim into the new spec โ never silently fork (2026-06-10: #5103 overrode #4788 condition 1 only; K6 decisions inherited).
External-framework/article brainstorms โ audit existing primitives before framing greenfield. When the request is "apply the technique(s) from this paper/article/framework to Soleur" (as opposed to a prior Soleur artifact), the first move is an existing-primitive audit, NOT a from-scratch design. First verify the source is real (WebSearch/WebFetch the paper + repo โ fabricated frameworks are a live failure mode), then translate each concept in the source into Soleur's current primitive and its automation level, and prompt the research/leader agents to "MAP THE CURRENT STATE and find the ONE open gap โ do not propose from scratch." The productive deliverable is a stageโprimitiveโautomationโgap table that scopes the smallest zero-risk increment closing the open stage. Why: 2026-07-05 self-improving-harness brainstorm (#6037) โ Soleur already implemented ~70% of Self-Harness/HarnessX (cron-compound-promote, rule-metrics-aggregate, eval-gate/ADR-069, #397 self-healing Layer 2, #5768 harness-L3) before the article existed; greenfield framing would have re-specced shipped infra. See knowledge-base/project/learnings/2026-07-05-external-framework-brainstorm-audit-existing-primitives-before-greenfield.md.
Run these agents in parallel to gather context before dialogue. Spawn domain leaders (Phase 0.5) and research agents (Phase 1.1) in one parallel batch via run_in_background: true โ they're independent. While agents run, use the wait time for local prior-art file checks and parent/sibling issue inspection rather than blocking on a wakeup. Why: 2026-05-11 #2720 brainstorm โ 4 leaders + 2 research agents in one batch returned in 60-180s vs. ~10 min sequenced.
What to look for:
knowledge-base/project/learnings/ -- past gotchas, patterns, lessons learned that might inform WHAT to build.github/workflows/scheduled-*.yml for credential-triple consumers โ runtime config inventory is reliably ~50% of true blast radius." Operators write feature descriptions from the runtime-rotation mental model; scheduled CI workflows typically hold a separate credential class (cron-checkin keys, write-only beacons) invisible from that vantage. See knowledge-base/project/learnings/2026-05-16-repo-research-must-inventory-scheduled-ci-workflows-for-secret-sweeps.md.Verifying "is X mounted/wired/enabled?" claims. When a research agent (or your own reasoning) asserts that a component is not present, not mounted, or not wired up, verify by grepping for the specific consuming symbol (a variable, hook, state field, or imported component name) rather than relying on absence of a generic phrase. Absence of the feature name in search results is not evidence of absence in code. Same applies to file-existence claims: when a subagent reports "file X does not exist on disk," independently verify with ls <absolute-worktree-path> from the orchestrator before propagating into brainstorm artifacts โ subagent CWD or path-resolution can produce false negatives, particularly across worktree vs. bare-repo paths. Why: In the 2026-04-17 session, the Explore agent reported the chat cost badge was "not confirmed to be rendered" because it grepped "cost badge" (no code match); the badge was in fact mounted via usageData.totalCostUsd in chat-surface.tsx, which a targeted grep for the state identifier would have caught. Why (file-existence): 2026-05-10 brainstorm of #2719 โ CLO subagent reported 2026-05-09-evaluating-vendor-branded-claude-code-skills.md missing; compound-time verification found it exists, the false negative had already been written into the brainstorm document and required a correcting edit. Same applies to "reuse the X-query code in file Y" claims: grep file Y for the specific external-API symbol the new code needs (the read endpoint, the auth-token var) before accepting the reuse premise โ a file that WRITES to a vendor (POST heartbeat, webhook, ingest DSN) is NOT evidence it can READ from that vendor; write-auth and read-auth are distinct credential/env surfaces. Why (reuse-direction): 2026-05-30 #4654 โ issue body said "reuse the Sentry-query code in cron-inngest-cron-watchdog.ts", but the watchdog reads Inngest /v1/functions and only POSTs Sentry heartbeats; the Sentry check-in read was net-new and needed an undefined auth token. Same applies to your own capability claims: before bounding the brainstorm's options with "tool X is GUI-only / can't do Y", grep/read the source first or phrase it as a question (hard rule hr-verify-repo-capability-claim-before-assert). Same applies to a GENERATED artifact's CONTENT: before characterising what a generated file contains in a prompt to another agent ("model-generated prose", "free-text", "arbitrary user input"), read the GENERATOR's emission lines โ file existence and content shape are separate claims, and a wrong content claim laundered through a subagent comes back as corroboration. Why (generated-content): 2026-07-23 #6882 โ weakness-digest.md was called "model-generated prose" in the CLO prompt and the CLO repeated it back; scripts/weakness-miner.sh emits only basename + tag labels + counts.
Verifying "this is a regression of #N" claims. When the feature description (or your framing) attributes a post-deploy symptom to a recently-merged PR, do NOT accept the attribution until the symptom's trigger path is traced end-to-end: grep the literal rendered string โ locate the render condition โ identify the state/event that triggers it โ cross-check that trigger path against the PR's file diff. If the PR did not modify any file on that path, the symptom is NOT a regression of that PR โ it is a distinct latent bug or an adjacent uncovered code path. See knowledge-base/project/learnings/2026-04-23-verify-trigger-path-before-attributing-regression.md.
Verifying referenced PR/issue state. When the feature description references an adjacent PR or issue (e.g., "PR #N adds X" / "this is the durable fix for #N"), verify the referenced state with gh pr view <N> --json state,mergedAt + a grep for the specific symbol the PR is supposed to have introduced (e.g., git grep -l "<symbol>" main) BEFORE accepting any sequencing claim from the issue body or weaving it into domain-leader prompts. Issue bodies are written at one point in time and aren't updated when adjacent PRs land or stall. A "PR #N is merged" claim that is false will produce internally-coherent leader recommendations premised on a wrong factual floor (e.g., a CPO "park this" recommendation premised on a bridge fix that hasn't actually shipped). For long-running brainstorms (>30 min between session-start verification and option presentation), re-run the same gh pr view <N> --json state,mergedAt check immediately before presenting architecture options whose pros/cons turn on prereq PR state โ parallel sessions can merge a prereq mid-brainstorm and dissolve option premises (2026-05-10 #3509 brainstorm: prereqs #3495 and #3508 both merged during the session, dissolving two of three presented options). See knowledge-base/project/learnings/2026-05-07-brainstorm-verify-referenced-pr-state-and-leader-infra-claims.md.
Enumerating umbrella child PRs before spawning leaders. When the feature description references a GitHub umbrella issue (#N) AND that issue is OPEN AND its body mentions sub-PRs by letter ("PR-A", "PR-B", "Stage 1", "Phase 1") OR enumerates increments/slices, run gh pr list --state all --search "<branch-slug-from-issue-body>" --json number,state,title,mergedAt --limit 20 BEFORE spawning Phase 0.5 leaders. The output is the source of truth for "what already shipped" โ pass the merged-PRs list into every domain-leader prompt's context section so leader recommendations are not premised on stale decompositions. tasks.md / spec.md checklist files lag merged work (the in-flight PR may have closed boxes that never got back-checked into main, and umbrella issue bodies are written-once at decomposition time). Distinct from the adjacent gh pr view <N> check above (single named PR) and the cited-flag-symbol check below (named architectural mechanism) โ this targets the multi-stage decomposition pattern specifically. Why: 2026-05-15 #3244 brainstorm โ CTO leader read stale tasks.md showing ยง1.5-1.8 unchecked and recommended "finish PR-B"; PR-B (#3395) had merged 9 days earlier on the sibling feat-agent-runtime-platform-pr-b branch. See knowledge-base/project/learnings/2026-05-15-brainstorm-enumerate-umbrella-child-prs-before-leader-spawn.md.
Verifying "approach 1 vs approach 2" claims. When the feature description (or the referenced issue body) proposes named architectural approaches AND cites a parent PR or recent commit, grep main for the symbol that approach 1 would introduce (a function name, callback hook, or call site mentioned in the issue body) BEFORE Phase 0.5 leader spawn. Presence-on-main is a strong staleness signal โ the brainstorm should pivot to audit residual risk not design the fix. Five seconds at Phase 1.1 saves a multi-leader spawn at Phase 2. This is sharper than the adjacent gh pr view check above because an adjacent PR (not the cited one) commonly implements the approach. See knowledge-base/project/learnings/2026-05-11-brainstorm-grep-approach-hook-before-spawning-leaders.md.
Treating claude[bot] / bot-fix/attempted comments as read-only context, not recommendations. When the issue carries a bot-fix/attempted label or claude[bot] comment trail, the bot's chosen fix shape optimized for the fix-issue skill's single-file constraint โ not for brand-survival or user-impact threshold. Read what the bot tried for context, then re-derive the fix shape from leader consensus (Phase 0.5). The bot's "needs multi-file" bail-out is a handoff signal, never an endorsement of the partial shape it attempted. See knowledge-base/project/learnings/2026-05-07-bot-fix-single-file-constraint-not-a-signal-for-brainstorm-fix-shape.md.
Cross-checking leader infra/substrate claims against repo-research. When a domain leader (CTO, CPO, etc.) returns a recommendation that names a specific substrate ("use Vercel cron", "Edge Function + cron poll", "the existing X queue") with phrasing like "already wired" / "already running" / "identical auth model", verify the claim with a targeted grep BEFORE treating it as authoritative. Read the parallel repo-research report first โ leader agents reason strategically and may prescribe substrates that don't exist in this codebase. If grep returns zero matches for the substrate's diagnostic symbol (cron config, setInterval site, Edge Function directory), treat the leader recommendation as a NEW substrate proposal (with the ops cost that entails), not a "use what's there" recommendation. Why: 2026-05-12 D-DSAR-art15 brainstorm โ CTO recommended "Vercel cron + serverless" with "already running" phrasing; repo-research confirmed no Vercel cron and no Edge Functions directory were wired (only pg_cron + one setInterval site). Catching this at brainstorm produced three candidate substrates in Open Questions; missing it would have produced a spec premised on infra that doesn't exist. See knowledge-base/project/learnings/2026-05-12-anticipatory-hook-bypass-and-leader-substrate-cross-check.md.
Auditing new online write surfaces against existing detection primitives. When a brainstormed proposal adds a new write surface (HTTP route, callback, CLI tool, scheduled writer) to any Doppler config, GH Actions secret, Supabase table, repo-tracked file, or DNS record, grep .github/workflows/scheduled-*.yml + .claude/hooks/ + plugins/soleur/skills/*/scripts/ for existing detection primitives (cron, hook, validator, audit) that READ from that same surface. If any detector reads from the proposed write target, the detector's invariant silently regresses โ the detector now compares attacker-writable inputs against themselves (x == x tautology). Either move the detector's "expected" side out-of-band (signed file in the repo, separate config the write path cannot reach) in the same PR, or scope-cut to avoid the online write. Surface this BEFORE Phase 2 approach selection โ once architecture options are anchored on the online-write substrate, the scope cut becomes a re-spec. Why: 2026-05-20 #4115 brainstorm โ issue body proposed an HMAC-gated callback writing 5 GitHub-App credentials to Doppler prd; scheduled-github-app-drift-guard.yml (#3187) reads those same credentials to assert App-identity immutability. Adding the write path would have silenced the drift-guard by making both sides of its compare attacker-rewritable. CTO surfaced this at Phase 0.5; the response was a scope cut to manifest-only. See knowledge-base/project/learnings/2026-05-20-online-write-on-source-of-truth-breaks-detection-invariant.md.
Verifying a cited infra/domain-auth requirement against the IaC root before sizing it as an in-feature checklist item. When the issue body lists an infra prerequisite (SPF/DKIM/DMARC/MX for domain X, a Cloudflare zone, a Terraform-managed resource) as one checkbox among many, grep the IaC root (apps/web-platform/infra/*.tf) for the domain/zone BEFORE accepting it as an in-feature task. If the zone is absent from IaC, it is a blocking zone-onboarding prerequisite (its own onboarding cost + token-reachability question per hr-fresh-host-provisioning-reachable-from-terraform-apply), not a checkbox โ file it as a dependency and sequence it first. A capability-existence claim tends to understate what exists (grep the primitive symbol); an infra-readiness claim tends to overstate readiness by listing a not-yet-provisioned zone (grep the IaC root) โ opposite failure directions, different probes. "Inbound already works at ops@domain" does NOT imply the zone is IaC-managed. Why: 2026-06-15 #5325 brainstorm โ issue listed "SPF/DKIM/DMARC for jikigai.com" as a checklist item, but infra/dns.tf is single-zone (soleur.ai); jikigai.com was in zero Terraform, making it a blocking prereq. See knowledge-base/project/learnings/2026-06-15-brainstorm-verify-cited-infra-prereq-against-iac-root.md.
A "connect X / set up X" CTA is a capability claim โ grep the ingestion + record-attribution path before sizing it. When the feature description adds an affordance presuming an underlying integration ("CTA to connect the founder's Gmail/Proton", "set up your email", "link your calendar"), grep the data-ingestion/config path BEFORE folding it into scope: the webhook/receive route, the env var or column that attributes records to a user/workspace, and the IaC for the address/credential. Single-tenant infra constants (a *_OWNER_USER_ID env, one provisioned address) routinely masquerade as multi-tenant features in a request. If attribution is a hardcoded constant, the CTA has nothing real to link to โ decouple: ship the presentation surface now, file the connection capability as its own brainstorm (CLO+Ops+CTO for mailbox/OAuth scope). Run the probe DURING dialogue, not after. Why: 2026-06-18 #5512 โ "connect email (Google/Proton)" CTA presumed multi-tenant ingestion, but the inbox is single-tenant (fixed operator ops@ address + EMAIL_TRIAGE_OWNER_USER_ID, email-on-received.ts:310); decoupled to #5527. See knowledge-base/project/learnings/2026-06-18-brainstorm-verify-cta-presumed-capability-before-scoping.md.
Reconciling fast-returning leader recommendations with later-arriving research findings. Phase 0.5 leaders typically return in 20โ40 s; learnings + repo research can take 2โ5ร longer. If a research agent surfaces evidence that contradicts a leader's recommendation (e.g., the leader recommends retrofitting /goal into test-fix-loop, but research surfaces that test-fix-loop already uses deterministic exit-code gates that /goal would duplicate at higher cost), name the contradiction explicitly and either re-prompt the contradicted leader with the research findings OR re-scope the approach BEFORE Phase 1.2 dialogue begins. "Weave each leader's assessment alongside research" is too soft when the two disagree; the leader-shaped framing wins by default unless the brainstorm parent forces a reconciliation pass. Why: 2026-05-15 /goal-primitive brainstorm โ CTO at t=35s recommended test-fix-loop as pilot retrofit candidate; learnings-researcher at t=124s and repo-research at t=215s independently showed the existing exit-code gate + Soleur's 316-line ralph-loop Stop hook made the entire retrofit premise obsolete. Without explicit reconciliation, the brainstorm would have proposed a worse approach the leader had already committed prose to. See knowledge-base/project/learnings/2026-05-15-brainstorm-leader-research-sequencing-and-prior-art-cwd.md.
Confirming the target-state premise with the operator BEFORE the first leader spawn (architecture issues). For an architecture brainstorm, the target end-state is the premise every Phase 0.5 leader reasons from. When the issue does not state it, do NOT infer it from current runtime state and spawn leaders โ a runtime snapshot (e.g. "web-2 pinned at LB weight 0", "single-active by design") is often a temporary bootstrap condition, not the design intent, and leaders will build internally-coherent recommendations on whatever floor you give them. Surface the inferred target-state and confirm it via one AskUserQuestion BEFORE the first leader spawn; a wrong floor costs a whole parallel round (and can fully reverse the verdict). Why: 2026-07-07 #6178 inngest-host brainstorm โ the CPO/CLO/CTO+platform-strategist triad recommended "in-place decouple + close as YAGNI" premised on inferred single-active; the operator's real target (active-active-N web) reversed it to mandatory extraction. See knowledge-base/project/learnings/2026-07-07-brainstorm-confirm-target-state-before-leader-spawn.md.
Verifying issue-body architectural constraints against the plugin-wide rule corpus. When the feature description quotes an architectural constraint from the issue body (e.g., "no stdlib Python CLI", "no X allowed in skills"), verify it against plugins/soleur/AGENTS.md and a spot-check of plugins/soleur/skills/**/scripts/ BEFORE letting it bound the option space at Phase 2. Issue bodies are written at one point in time and drift from the plugin's actual practice; uncritically accepting a constraint that overstates the rule cuts off viable architectures and biases toward heavier alternatives. See knowledge-base/project/learnings/2026-05-12-brainstorm-defer-decision-issue-body-rule-drift-and-oauth-only-bundling-scope-bound.md Pattern 1.
Verifying cited-plan-doc code claims against main, not just issue bodies. When the feature description cites a prior plan/spec/brainstorm doc, treat its concrete code claims (component names, route paths, exact HTTP-status behavior) as point-in-time prose that drifts from code โ NOT as a more authoritative source than the code it describes. Grep main for the specific symbol (the component name, the route file + the literal status code) BEFORE letting the claim bound Phase 2. A doc authored "against live prod data" earns trust on the DB values it actually measured, but its code-shape claims are often paraphrased or misremembered. #4712: the plan named a RepoConnectionCard that exists nowhere in code (real surface = ProjectSetupCard) and asserted /api/kb/tree 409s on repo_status='error' (it 404s/503s; the 409s are in /api/kb/sync) โ both caught by repo-research grep before they shaped the spec. See knowledge-base/project/learnings/2026-06-01-brainstorm-verify-cited-plan-doc-claims-not-just-issue-body.md.
Verifying issue-body option enumerations against library API surface. When the issue body names approaches "Option A / B / C" with one marked Recommended, grep the relevant library's .d.ts / framework types / MCP schemas for additional degrees of freedom (extra config primitives, hooks, formatters, serializers, middleware) BEFORE accepting the listed enumeration. The "Recommended" tag is the reviewer's vote against the alternatives they considered, not a vote against alternatives they missed; inventory grep + API-surface grep can surface a 4th option that dominates the 3 listed. Also re-run any inventory count cited in the issue body โ drift between issue creation and brainstorm is common (e.g., 27 โ 10 in 6 hours when a parallel PR absorbed sites). See knowledge-base/project/learnings/2026-05-12-brainstorm-issue-body-option-and-inventory-staleness-pino-userid.md.
Verifying cited flag/symbol against main before spawning leaders. When the issue body cites a capitalized symbol (FLAG_*, ENABLE_*, USE_*, FEATURE_*, *_ENABLED) or an uppercase camel-case feature name as the gating mechanism, grep main for the symbol and read the first ~20 lines of each match for a retirement comment (retire|removed|deprecated|sunset) BEFORE spawning leaders. The retirement-comment-in-owning-module is a high-signal failure mode for follow-through and Stage-N issues โ multi-stage plans create child issues that describe a gating mechanism the parent assumed, then a subsequent stage or out-of-band PR retires it while the child issue's body is never updated. A 30-second grep at Phase 1.1 saves a multi-leader spawn premised on the wrong scope (the catch otherwise happens at Phase 0.5 leader convergence, costing 3-5 min of parallel agent compute and forcing every leader to mid-assessment reframe). Distinct from the gh pr view check (adjacent-PR claims) and the approach-hook check (named architectural approaches) above โ this targets cited symbols still referenced by name in the issue's own body. See knowledge-base/project/learnings/2026-05-13-brainstorm-grep-cited-flag-symbol-against-main-before-spawning-leaders.md.
Verifying whether a referenced artifact exists but is only half-wired (capture layer shipped, enforcement unwired). When an issue frames work as "build X" AND a sibling PR has recently merged, grep the worktree for the cited table/migration/resolver/symbol BEFORE spawning leaders โ and if it exists, read its body to find which layer is missing. A data/capture layer and its enforcement/gating layer are separable; a prior PR commonly ships the easy reviewable half (table + route + display) while deferring the runtime-behavior half (the gate that actually changes behavior). "Build X" is a claim about desired end state, not about what's on main. The real gap is then narrower and sharper than the issue's greenfield framing โ leaders premised on "design from scratch" waste cycles re-deriving shipped code. Distinct from the gh pr view state check (whether referenced work is stale) โ this targets the referenced artifact existing but only partially wired. See knowledge-base/project/learnings/2026-05-29-brainstorm-sibling-pr-shipped-capture-layer-enforcement-gap.md.
Verifying PIR-follow-up "build detection / build a probe" framings against the observability layer + sibling-PR merge dates. A PIR follow-up is typically authored while its author is focused on the recovery PR in flight, and discounts detection work that sibling PRs shipped between the incident and the issue-filing date. Before accepting a "detection still depends on a user noticing / add a scheduled probe" framing: (1) grep the observability layer for the proposed mechanism โ cron-*.ts Inngest functions AND infra/sentry/*.tf โ not just app code; the probe may already exist and the only gap is the alert rule on its events (hr-no-dashboard-eyeball-pull-data-yourself); (2) diff the sibling-PR mergedAt against the issue createdAt (gh pr view <N> --json mergedAt vs gh issue view <M> --json createdAt) โ arms that merged BEFORE the issue was filed invalidate an "X doesn't exist" premise even on a brand-new issue; (3) verify the row/event shape the proposed condition produces, to confirm whether an existing blanket check already covers it. Why: 2026-06-03 #4882 โ issue proposed building a KB-sync-stale detection probe; cron-workspace-sync-health.ts arms #4712/#4717 had shipped it two days prior, and the only real gap was a missing sentry_issue_alert. See knowledge-base/project/learnings/2026-06-03-brainstorm-grep-observability-layer-before-greenfield-detection-framing.md.
Verifying whether the target table is append-only before accepting an "edit the row" framing. When the feature proposes mutating an existing row (rotate a token, reset an expiry, swap a value) on a table that stores audit/PII/lineage data, grep for a *_no_mutate trigger, WORM comment, or "immutable once set" guard BEFORE accepting the in-place-edit framing: git grep -nE "no_mutate|is immutable|immutable" -- '<migration-glob>'. If the column is immutable, the operator's "edit the record" mental model is incompatible with the schema โ the aligned pattern is revoke-old-row + insert-new-row in one SECURITY DEFINER transaction (the old token/link dies because accept/lookup already reject revoked rows; atomic by construction; no trigger change). Catching this at Phase 1.1 turns a doomed in-place RPC into the correct supersede pattern. Why: 2026-05-29 #4636 resend-invite โ workspace_invitations_no_mutate (075:93) makes token_hash/expires_at immutable; CTO+CLO surfaced it, verified by direct migration grep. See knowledge-base/project/learnings/2026-05-29-brainstorm-grep-worm-trigger-before-accepting-in-place-edit-framing.md.
Verifying data-source granularity for per-X aggregation claims. When the issue body proposes a mechanism keyed on "read <file> for per-X counts" (per-user, per-tenant, per-rule, per-learning, per-skill), the existence probe (ls path) is necessary but insufficient โ probe the file's actual entity granularity via git show main:<path> | jq 'keys, (.rules // .entries // [])[0]' BEFORE accepting the proposed mechanism. A file present on main can still be the wrong substrate: e.g., knowledge-base/project/rule-metrics.json's .rules[].id are AGENTS.md rule slugs (cm-challenge-reasoning-instead-of), not learning file paths โ so "read rule-metrics.json for per-learning hit counts" (#4042 issue body) is mechanically impossible regardless of file existence. 10 seconds at Phase 1.1 saves a full Phase 0.5 leader fan-out on a wrong-premise feature. Distinct from the file-existence check, the cited-flag-symbol check, and the architectural-constraint-against-rule-corpus check above. See knowledge-base/project/learnings/2026-05-19-brainstorm-pre-committed-ladder-and-data-source-granularity-check.md Pattern 1.
Verifying issue-body mechanical disambiguators against runtime state before leader spawn. When the issue body enumerates a probe (curl, gh api, DSN-substring read, config lookup) whose result would narrow multiple speculative remediation tracks to one, run it BEFORE Phase 0.5 leader spawn. Cost: seconds. Benefit: leader prompts become single-track and correctly-thresholded instead of speculating across N branches of which one is real. Distinct from the approach-hook check (whether named work is still relevant) and the cited-flag check (whether named gates still exist) โ this answers which of N speculative branches is real when the issue body itself names how to find out. Why: 2026-05-15 #3861 brainstorm โ issue enumerated three Sentry-residency remediation tracks; a 5-second DSN cluster-substring read from Doppler prd (o<id>.ingest.de.sentry.io) collapsed the three speculative tracks to one and softened the brand-survival framing from "Article 33 statutory clock" to "misleading ยง5(2) accountability evidence" before the CPO+CLO+CTO triad spawn. See knowledge-base/project/learnings/2026-05-15-brainstorm-probe-first-before-leader-spawn.md.
A cumulative counter cited as a loop/churn signal is meaningless without its window โ read stats_reset first; and a "residual" is unmeasurable while the dominant source it's residual to is still in the window. When an issue cites pg_stat_statements call counts (or any cumulative metric โ Sentry event totals, cron run tallies, WAL calls) as evidence of a runaway loop or hot path, query the counter's reset timestamp (SELECT stats_reset FROM pg_stat_statements_info) and divide by the window length AND the active-user count before accepting the framing โ a "high" number is usually a long window, not a loop. Separately, when the issue is a residual of a just-landed fix ("the second-largest source after PR #N"), cumulative stats still show the fixed source dominating until the counter is reset, so the true residual share is unmeasurable until you reset + soak โ the brainstorm's deliverable is often "reset and re-measure," not "design the optimization." Why: #5739 โ 1,586 recovery_token UPDATEs read as a loop but were ~29/day over a 55-day window (no loop); the auth-WAL "residual" couldn't be sized until pg_stat_statements was reset post-#5736. See knowledge-base/project/learnings/2026-06-30-pgss-window-and-reset-before-measuring-residual.md.
Verifying live-vs-paused state when the framing is "restore the paused X / unblock the held-back Y." "Paused" and "needs containment" are independent axes โ an issue author writing from the in-flight-PR mental model often frames an adjacent uncontained-but-LIVE actor as "future work" while the thing they just paused feels like "the dangerous thing." Before accepting the framing, verify every named actor against the runtime pause/defer registry (the defer-set / manifest), NOT the issue prose: grep the defer set + grep each "needs-a-boundary-before-it-runs" actor for its pause guard + confirm it's registered/live. If an actor named as future-work is already running, the work is containment of a live exposure, not unblock of paused work โ which flips the brand-survival threshold and the sequencing options. Why: 2026-06-09 #5046 โ issue titled "restore the paused crons" framed 4 spawn("bash") crons as future firewall work; they had no deferIfTier2Cron guard in cron-manifest.ts and were running live/uncontained, while the 11 "paused" crons were the safe population. See knowledge-base/project/learnings/2026-06-09-restore-paused-framing-can-invert-risk-ordering.md.
Tier 2 cannibalization lens for competitive-audit umbrella candidates. When the feature description is a single candidate from a competitive-audit umbrella's Tier 2 list, list the umbrella's explicit reject decisions, count how many sibling candidates already shipped, and ask "if we ship N more, do we reconstruct the rejected outcome?" If yes, the bar for this candidate is higher than its own merits โ surface the cumulative count in the Domain Assessments so reviewers see the pattern. See knowledge-base/project/learnings/2026-05-12-brainstorm-defer-decision-issue-body-rule-drift-and-oauth-only-bundling-scope-bound.md Pattern 3.
This skill should be used when auditing the recurring per-Anthropic-model-release checklist (model IDs, claude-code-action pin freshness, pricing drift, tier-map re-evaluation): it auto-fixes stale model-ID swaps into a CI-gated PR and flags the rest.
This skill should be used when performing exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees.
This skill should be used when designing agent-native applications where agents are first-class citizens: architecting autonomous agents, creating MCP tools, building apps where features are agent-driven outcomes.
This skill should be used when working with DSPy.rb, a Ruby framework for type-safe, composable LLM applications.
This skill provides a promptfoo eval harness that measures whether a Soleur skill or agent edit actually improves behavior, comparing a skill arm against a baseline control arm.
This skill should be used when resolving all TODO comments in the codebase using parallel processing. It analyzes dependencies, creates a resolution plan with a mermaid flow diagram, and spawns parallel resolver agents.