devflow-kit 3.1.0 → 3.3.0

package/dist/commands/debug.md

@@ -15,7 +15,13 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/debug`:
+What follows `/debug` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Bug description: "login fails after session timeout"
 - Issue reference: "#42"
 - Empty: use conversation context
@@ -26,8 +32,6 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 **Produces:** DECISIONS_CONTEXT
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:software-design`, `devflow:testing`. If a skill fails to load, continue without it.
-
 ### Load DECISIONS_CONTEXT
 
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
@@ -66,9 +70,9 @@ The orchestrator uses `DECISIONS_CONTEXT` locally when generating hypotheses (Ph
 **Produces:** HYPOTHESES, BUG_CONTEXT
 **Requires:** DECISIONS_CONTEXT
 
-If `$ARGUMENTS` opens with a candidate issue reference, fetch the issue:
+If `COMMAND_INPUT` opens with a candidate issue reference, fetch the issue:
 
-**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `$ARGUMENTS` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
+**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `COMMAND_INPUT` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
 
 **A token of any other shape is neither coerced nor dropped silently — and no producer-side grammar check rejects it before the fetch.** Adjudication belongs to the operation that runs, and each one answers in its own Output block: `fetch-issue` strips a leading `#` and takes the text branch, so a non-numeric token is used as a **search term** and the operation returns the first open match or nothing; `fetch-issues-batch` resolves each token to an issue number, drops the ones it cannot resolve, and names them in `NOT_FOUND ({refs})` beside the issues it did fetch. Read the outcome from the operation that ran — a token's shape is a verdict nowhere, and there is nothing upstream holding it back.
 
@@ -119,7 +123,8 @@ Return a structured report:
 - Status: CONFIRMED / DISPROVED / PARTIAL
 - Evidence FOR: [list with file:line refs]
 - Evidence AGAINST: [list with file:line refs]
-- Key finding: {one-sentence summary}"
+- Key finding: {one-sentence summary}
+Keep the whole report to at most about 1,500 tokens."
 
 Agent(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
@@ -127,7 +132,7 @@ Agent(subagent_type="Explore"):
 Hypothesis: {hypothesis B description}
 Focus area: {specific code area, mechanism, or condition}
 
-[same steps and return format]"
+[same steps and return format; the whole report at most about 1,500 tokens]"
 
 Agent(subagent_type="Explore"):
 "Investigate this bug: {bug_description}
@@ -135,7 +140,7 @@ Agent(subagent_type="Explore"):
 Hypothesis: {hypothesis C description}
 Focus area: {specific code area, mechanism, or condition}
 
-[same steps and return format]"
+[same steps and return format; the whole report at most about 1,500 tokens]"
 
 (Add more investigators if bug complexity warrants 4-5 hypotheses)
 ```
@@ -147,7 +152,7 @@ Focus area: {specific code area, mechanism, or condition}
 
 Evaluate investigation verdicts before synthesis:
 
-- **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias)
+- **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias), each reporting at most about 1,500 tokens
 - **Multiple PARTIAL**: Look for a unifying root cause that explains all partial evidence
 - **All DISPROVED**: Report honestly — "No root cause identified from initial hypotheses." Generate 2-3 second-round hypotheses if conversation context suggests avenues not yet explored. Loop back to Phase 3.
 
@@ -239,7 +244,7 @@ If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -256,8 +261,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md