devflow-kit 3.3.0 → 3.4.0

package/dist/learning-off/commands/explore.md

@@ -0,0 +1,210 @@
+---
+description: Explore codebase with structured analysis and optional feature knowledge creation
+---
+# Explore Command
+
+Explore a codebase area by spawning parallel agents for flow tracing, dependency mapping, and pattern analysis. Findings are synthesized into structured output with file:line references, with optional feature knowledge created as a byproduct.
+
+## Usage
+
+```
+/explore "how does the auth system work"
+/explore "trace the request lifecycle from API to database"
+/explore "what patterns does the payments module use"
+```
+
+## Input
+
+What follows `/explore` 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:
+- Area description: "how does the auth system work"
+- Flow question: "trace the request lifecycle"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Resolve Settings
+
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root when the run has one worktree:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+
+The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+
+**No up-front feature knowledge load** — explore investigation workers read code directly to avoid confirmation bias. Feature knowledge is only created as a write-back at the end, after exploration is complete.
+
+### Phase 2: Orient
+
+**Produces:** ORIENT_OUTPUT
+
+Spawn `Agent(subagent_type="Skim")` to get codebase overview relevant to the exploration question:
+
+- File structure and module boundaries in the target area
+- Entry points and key abstractions
+- Related patterns and conventions
+
+### Phase 3: Explore
+
+**Produces:** EXPLORE_OUTPUT
+**Requires:** ORIENT_OUTPUT
+
+Based on Skim agent findings, spawn 2-3 `Agent(subagent_type="Explore")` agents **in a single message** (parallel execution):
+
+- **Flow explorer**: Trace the primary call chain end-to-end — entry point through to side effects
+- **Dependency explorer**: Map imports, shared types, module boundaries, and integration points
+- **Pattern explorer**: Identify recurring patterns, conventions, and architectural decisions in the area
+
+Adjust explorer focus based on the specific exploration question.
+
+Ask each explorer for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
+
+### Phase 4: Synthesize
+
+**Produces:** MERGED_FINDINGS
+**Requires:** EXPLORE_OUTPUT
+
+Spawn `Agent(subagent_type="Synthesize")` in `exploration` mode with combined findings:
+
+- Merge overlapping discoveries from parallel explorers
+- Resolve any contradictions between explorer findings
+- Organize into the Output format below
+
+### Phase 5: Present
+
+**Requires:** MERGED_FINDINGS
+
+Main session reviews synthesis for:
+
+- **Gaps**: Areas the explorers missed or couldn't reach
+- **Surprises**: Unexpected patterns, hidden dependencies, non-obvious design choices
+- **Depth**: Areas where the user might want to drill deeper
+
+Present findings to user. Use AskUserQuestion to offer focused follow-up exploration.
+
+### Phase 6: Suggest Feature Knowledge Creation (Conditional)
+
+**Requires:** MERGED_FINDINGS
+**Produces:** FEATURE_KNOWLEDGE_STATUS (created | skipped)
+
+1. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
+2. Use AskUserQuestion: "No feature knowledge exists for {explored area}. Create one to capture these patterns?"
+3. If user declines → set FEATURE_KNOWLEDGE_STATUS = skipped
+4. If user accepts: proceed with write-back below.
+
+### Feature Knowledge Write-Back (Conditional)
+
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+
+**Step 1 — Check the opt-out gate, with `{root}` = `{worktree}`:** take the settings line resolved above for that root, resolving it with the settings block when this run has not yet.
+
+If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine switch (`devflow knowledge --disable`), the repository and the personal settings can each turn knowledge off, and none can turn it back on (D-FEATURES-NARROW-ONLY). The fail-closed line says `KNOWLEDGE=off` too, so an unresolvable line skips write-back.
+
+**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). 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.
+
+**Step 3 — Spawn the Knowledge agent:**
+
+Spawn `Agent(subagent_type="Knowledge")` with the following context:
+
+```
+"WORKTREE_PATH: {worktree root}
+FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
+FEATURE_NAME: {human-readable name}
+DIRECTORIES: {list of primary directories touched by this workflow}
+FILES_CHANGED: {list of files changed}
+
+Write the knowledge base to:
+  {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
+
+Then update the index cache by performing a read-modify-write on:
+  {worktree}/.devflow/features/index.md
+
+Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
+
+If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
+
+The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
+
+After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+```
+
+**Step 4 — Surface an uncommitted knowledge base:**
+
+When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files were written but deliberately not committed — a commit on a detached HEAD becomes unreachable once HEAD moves. Tell the user in the workflow's final report, in one line, that the knowledge base was written but not committed, and name the uncommitted paths the agent listed, so they can commit them on a branch before the worktree is removed. Never commit them yourself.
+
+**Failure handling**: Non-blocking. If the Knowledge agent fails, log the failure and continue — the workflow outcome is not affected by write-back success.
+
+Set FEATURE_KNOWLEDGE_STATUS = created (if agent spawned) or skipped.
+
+**Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+Structured exploration findings with concrete code references:
+
+- Scope (what was explored and boundaries)
+- Architecture Map (modules, layers, key abstractions with file:line)
+- Flow Trace (call chain from entry to exit with file:line at each step)
+- Integration Points (module boundaries, shared types, external dependencies)
+- Patterns (recurring conventions, design decisions observed)
+- Key Insights (non-obvious findings, surprises, potential concerns)
+
+## Architecture
+
+```
+/explore (orchestrator)
+│
+├─ Phase 1: Resolve Settings
+│
+├─ Phase 2: Orient
+│  └─ Skim agent (codebase overview)
+│
+├─ Phase 3: Parallel exploration
+│  └─ 2-3 Explore agents (flow, dependency, pattern) in single message
+│
+├─ Phase 4: Synthesize
+│  └─ Synthesize agent aggregates findings in exploration mode
+│
+├─ Phase 5: Present findings with drill-down offer
+│
+└─ Phase 6: Suggest feature knowledge creation (conditional)
+   └─ Knowledge agent write-back (if user accepts and no existing feature knowledge)
+```
+
+## Principles
+
+1. **Structure over browsing** - Every claim must cite file:line references
+2. **Parallel execution** - All explorers run simultaneously for speed
+3. **Knowledge-informed** - NO pre-loaded feature knowledge in sub-agents (avoids confirmation bias)
+4. **User-driven depth** - Present findings, then offer drill-down into specific areas
+
+## Error Handling
+
+- If Skim agent returns no relevant files: report "No files found matching exploration scope"
+- If all explorers error: report partial findings from any that succeeded, note gaps
+- If an explorer errors: continue with remaining results, note the gap
+- If feature knowledge creation fails: log failure, report exploration results normally