@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/{xmc/workflows/4-implementation/xiaoma-dev-story/workflow.md → xmc-skills/4-implementation/xiaoma-dev-story/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: xiaoma-dev-story
+description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
+---
+
 # Dev Story Workflow
 
 **Goal:** Execute story implementation following a context filled story spec file.
@@ -5,17 +10,42 @@
 **Your Role:** Developer implementing the story.
 - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
 - Generate all documents in {document_output_language}
-- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
+- Only modify the story file in these areas: YAML frontmatter `baseline_commit`, Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
 - Execute ALL steps in exact order; do NOT skip steps
 - Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.
-- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
+- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 9 decides completion.
 - User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
 
----
+## Conventions
+
+- Bare paths (e.g. `steps/step-01-init.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
 
-## INITIALIZATION
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
-### Configuration Loading
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
 
 Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 
@@ -24,30 +54,35 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
 - `user_skill_level`
 - `implementation_artifacts`
 - `date` as system-generated current datetime
+- `project_context` = `**/project-context.md` (load if exists)
 
-### Paths
+### Step 5: Greet the User
 
-- `story_file` = `` (explicit story path; auto-discovered if empty)
-- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+Greet `{user_name}`, speaking in `{communication_language}`.
 
-### Context
+### Step 6: Execute Append Steps
 
-- `project_context` = `**/project-context.md` (load if exists)
+Execute each entry in `{workflow.activation_steps_append}` in order.
 
----
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Paths
 
-## EXECUTION
+- `story_file` = `` (explicit story path; auto-discovered if empty)
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+
+## Execution
 
 <workflow>
   <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
   <critical>Generate all documents in {document_output_language}</critical>
-  <critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List,
+  <critical>Only modify the story file in these areas: YAML frontmatter `baseline_commit`, Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List,
     Change Log, and Status</critical>
   <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
   <critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution
     until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives
     other instruction.</critical>
-  <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
+  <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 9 decides completion.</critical>
   <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
 
   <step n="1" goal="Find next ready story and load it" tag="sprint-status">
@@ -166,7 +201,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
     <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
 
     <action if="no incomplete tasks">
-      <goto step="6">Completion sequence</goto>
+      <goto step="9">Completion sequence</goto>
     </action>
     <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
     <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
@@ -226,26 +261,40 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
   </step>
 
   <step n="4" goal="Mark story in-progress" tag="sprint-status">
+    <action>If story file YAML frontmatter already contains `baseline_commit`, preserve the existing value and do not overwrite it</action>
+
     <check if="{{sprint_status}} file exists">
       <action>Load the FULL file: {{sprint_status}}</action>
       <action>Read all development_status entries to find {{story_key}}</action>
-      <action>Get current status value for development_status[{{story_key}}]</action>
+      <action>Set {{current_status}} to development_status[{{story_key}}]</action>
+    </check>
+
+    <check if="{{sprint_status}} file does NOT exist">
+      <action>Set {{current_status}} to the story file Status section value</action>
+    </check>
 
-      <check if="current status == 'ready-for-dev' OR review_continuation == true">
+    <check if="{{current_status}} == 'ready-for-dev' AND story file YAML frontmatter does NOT contain baseline_commit">
+      <action>Run `git rev-parse HEAD` to capture current commit into {{baseline_commit}}; if git/version control is unavailable, set {{baseline_commit}} = `NO_VCS`</action>
+      <action>If story file YAML frontmatter exists, add `baseline_commit: {{baseline_commit}}` to the frontmatter</action>
+      <action>If story file has no YAML frontmatter, create frontmatter at the top containing only `baseline_commit: {{baseline_commit}}`</action>
+    </check>
+
+    <check if="{{sprint_status}} file exists">
+      <check if="{{current_status}} == 'ready-for-dev' OR (review_continuation == true AND {{current_status}} != 'in-progress')">
         <action>Update the story in the sprint status report to = "in-progress"</action>
         <action>Update last_updated field to current date</action>
         <output>🚀 Starting work on story {{story_key}}
-          Status updated: ready-for-dev → in-progress
+          Status updated: {{current_status}} → in-progress
         </output>
       </check>
 
-      <check if="current status == 'in-progress'">
+      <check if="{{current_status}} == 'in-progress'">
         <output>⏯️ Resuming work on story {{story_key}}
           Story is already marked in-progress
         </output>
       </check>
 
-      <check if="current status is neither ready-for-dev nor in-progress">
+      <check if="{{current_status}} is neither ready-for-dev nor in-progress">
         <output>⚠️ Unexpected story status: {{current_status}}
           Expected ready-for-dev or in-progress. Continuing anyway...
         </output>
@@ -445,6 +494,7 @@ Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
       <action>Suggest checking {sprint_status} to see project progress</action>
     </check>
     <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
+  <action>Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>
   </step>
 
 </workflow>

package/src/xmc-skills/4-implementation/xiaoma-dev-story/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-dev-story. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its final step,
+# after the story implementation is complete and status is updated. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-investigate/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: xiaoma-investigate
+description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it.
+---
+
+# Investigate
+
+## Overview
+
+Reconstruct what's happening, or what an unfamiliar area does, from the available evidence. Produce a structured case
+file another engineer can pick up cold. Calibrate continuously between defect-chasing (symptom-driven) and
+area-exploration (no symptom); the same discipline applies on both ends.
+
+**Args:** A ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path
+to an existing case file. The last form resumes a prior investigation; everything else opens a new case.
+
+**Output:** `{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}`. Reference inputs
+are recorded; raw content is not read into the parent context until an outcome calls for it.
+
+`{slug}` is the ticket ID when one is provided, otherwise a short descriptive name agreed with the user, sanitized to
+lowercase alphanumeric with hyphens. On collision with an existing case file at the resolved path, ask whether to
+rename to `slug-YYYY-MM-DD.md` or resume the existing file (resuming routes to Outcome 0).
+
+After every outcome, present what was learned and pause for the user before continuing.
+
+## Principles
+
+- **Evidence grading.**
+  - **Confirmed.** Directly observed; cite `path:line`, log timestamp, or commit hash.
+  - **Deduced.** Logically follows from Confirmed evidence; show the chain.
+  - **Hypothesized.** Plausible but unconfirmed; state what would confirm or refute it.
+- **Stronghold first.** Anchor in one Confirmed piece of evidence and expand outward. Never start from a theory and
+  hunt for support. When evidence is sparse, switch to evidence-light mode (Outcome 1 branch).
+- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify independently; if evidence
+  contradicts, say so.
+- **Follow the evidence, not the narrative.** When evidence contradicts the working theory, update the theory — never
+  the other way around. Resist confirmation bias even when the user is convinced.
+- **Hypotheses are never deleted.** Update Status (Open / Confirmed / Refuted) and add a Resolution. Wrong turns are
+  part of the deliverable.
+- **Missing evidence is itself a finding.** Document the gap, what it would resolve, and how to obtain it.
+- **Write it down early.** Initialize the case file as soon as the slug is agreed; it is the persistent state across
+  interruptions.
+- **Path:line citations** use CWD-relative format, no leading `/`, so they're clickable in IDE-embedded terminals.
+- **Delegation discipline.** When a step requires reading 5+ files or any file >10K tokens, delegate to a subagent
+  that returns structured JSON only. Cite `path:line` from the result; don't re-read in the parent.
+- **Issue independent operations in parallel** (multi-grep, multi-read, parallel inventories) — one message, multiple
+  tool calls.
+- **Communication.** Evidence-first language ("the evidence shows", "unconfirmed, requires X to verify"). No hedging,
+  no narrative.
+
+## On Activation
+
+### Step 1: Resolve the workflow block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+If the script fails, stop and surface the error.
+
+### Step 2: Execute prepend steps
+
+Run each entry in `{workflow.activation_steps_prepend}` in order.
+
+### Step 3: Load persistent facts
+
+Treat each entry in `{workflow.persistent_facts}` as foundational context. `file:` prefixes are paths or globs under
+`{project-root}` (load contents); other entries are facts verbatim.
+
+### Step 4: Load config
+
+Load `{project-root}/_xiaoma/xmc/config.yaml` and resolve `{user_name}`, `{communication_language}`,
+`{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If `{implementation_artifacts}` is
+unresolved, fall back to `./investigations/` and surface the fallback before initializing.
+
+### Step 5: Greet
+
+Greet `{user_name}` in `{communication_language}`.
+
+### Step 6: Execute append steps
+
+Run each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+### Step 7: Acknowledge and route
+
+Acknowledge the input as a reference (record paths and IDs; don't read raw content). Path to an existing case file →
+Outcome 0. Otherwise → Outcome 1.
+
+## Procedure
+
+### Outcome 0: Existing case is loaded and surfaced
+
+Read the case file. Surface, in order: open hypotheses (Status = Open) with their confirm/refute criteria; open
+backlog (Status ≠ Done); missing-evidence rows; last Conclusion with confidence. Ask which thread to pull. New
+evidence opens a new `## Follow-up: {YYYY-MM-DD}` block (append `#2`, `#3` on same-day reentry). Pause for user with the recap above; wait for direction.
+
+### Outcome 1: Scope and stronghold are established
+
+Acknowledge each input shape — record location, scope, time window only; bulk reads happen in Outcome 2.
+
+- **Issue tracker ticket.** Fetch full details via available MCP tools.
+- **Diagnostic archive.** Record path, file count, time window.
+- **Log file or stack trace.** Record path and time window; only the stack frame already in the user's message is in
+  scope here.
+- **Free-text description.** Capture verbatim; treat as hypothesis.
+- **Code area name** (no symptom). Record entry point.
+- **Recent commit area.** Record commit range.
+
+If the user arrived with a hypothesis, register it as Hypothesis #1. Find the stronghold *independently*; the user's
+hypothesis is one of the things the stronghold validates or refutes.
+
+Find a stronghold: a Confirmed piece of evidence (error message, function name, HTTP route, config parameter, test
+case). Anchor here.
+
+**Initialize `{case_file}` before branching.** The path is
+`{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}` with `{slug}` substituted (slug
+and collision rules in Overview). Create the file from `{workflow.case_file_template}` and fill Hand-off Brief
+(rough), Case Info, Problem Statement, initial Evidence Inventory.
+
+**Evidence-light branch.** When no Confirmed evidence is reachable: mark the case evidence-light in the Hand-off
+Brief; populate the Investigation Backlog with prioritized data-collection items; record "to make progress, I need one
+of: …"; pause for the user to provide evidence or authorize Outcome 2 to scan more broadly.
+
+Otherwise present scope, stronghold, file path, proposed approach. Pause for user with the recap above; wait for direction.
+
+### Outcome 2: Evidence perimeter is mapped
+
+Survey the scene: inventory available evidence in parallel across these independent categories: diagnostic archives;
+issue tracker; version control; test results; static analysis; source code. For any category exceeding ~10K tokens,
+delegate to a subagent that returns a JSON manifest (paths, sizes, time windows, key fragments cited as `path:line`).
+
+Classify each Available, Partial, or Missing — Missing is itself a finding. Update Evidence Inventory and Investigation
+Backlog. Pause for user with the recap above; wait for direction.
+
+### Outcome 3: Cause is reasoned about with discipline
+
+- **Trace causality.** Symptom-driven: trace backward from the symptom to producing conditions and the state that
+  emerged. Exploration: trace backward from outputs (returns, side effects, messages sent) to producing conditions.
+  Same technique, different anchor.
+- **Reconstruct the timeline** by cross-referencing logs, system events, version control, user observations.
+- **Form and test hypotheses.** State, identify confirming/refuting evidence, search, grade
+  (Confirmed / Refuted / Open). Update Status. Never delete.
+- **Refutation pass.** Each time a hypothesis transitions toward Confirmed, actively look for refuting evidence first.
+  Record the attempt in Resolution.
+- **Verify the user's premise.** If evidence contradicts, say so explicitly.
+- **Add discovered paths to the backlog.** Stay focused on the current thread.
+
+Update Confirmed Findings, Deduced Conclusions, Hypothesized Paths, Backlog, Timeline. Highlight contradictions to the
+original premise. Pause for user with the recap above; wait for direction.
+
+### Outcome 4: Source has been traced where it matters
+
+Issue these first-pass scans as parallel tool calls in one message: grep for exact error strings; glob the affected
+directory for parallel implementations; `git log` for recent changes.
+
+Then sequentially: read the surrounding code; follow the caller chain; watch for language and process boundary
+crossings (compiled→scripts, IPC, host→device, configuration flow).
+
+Lean by case type:
+
+- **Exploration:** I/O mapping (triggers, outputs, dependencies); frequent-terms scan; control-flow filtering
+  (branches, loops, error handling, state-machine transitions).
+- **Symptom-driven:** depth assessment — is the root cause reachable from local context, or is a broader area model
+  required? Surface escalations; never silently expand scope. Trivial-fix assessment — off-by-one, missing null check,
+  swapped argument → one-line code suggestion or draft diff in the report; non-trivial → stop at the root cause area.
+
+Investigation stops at the diagnosis; implementation is out of scope. Update Source Code Trace (Error origin, Trigger,
+Condition, Related files; area model when broader). Pause for user with the recap above; wait for direction.
+
+### Outcome 5: Report is finalized and the hand-off is clean
+
+Update `{case_file}`:
+
+- **Hand-off Brief** rewritten to final form (3 sentences, 15-second read).
+- **Final Conclusion** with confidence: **High** (Confirmed root cause, deterministic repro), **Medium** (Deduced;
+  minor uncertainty), **Low** (Hypothesized; clear data gap).
+- **Fix direction** when applicable (categorize by mechanism if multiple combine).
+- **Diagnostic steps** if uncertainty remains.
+- **Reproduction Plan** when applicable, or a verification plan for exploration cases.
+- **Status:** Active / Concluded / Blocked on evidence.
+
+Present the conclusion, then a concrete next-steps menu: trivial fix → `xiaoma-quick-dev`; scope/plan adjustment →
+`xiaoma-correct-course`; tracked story → `xiaoma-create-story`; fresh review → `xiaoma-code-review`. Recommend the
+highest-value action. Mitigations and workarounds are generated only on explicit request — investigation stops at the
+diagnosis. Execute `{workflow.on_complete}` if non-empty. Pause for user with the recap above; wait for direction.
+
+## Follow-up Iterations
+
+Continue work by appending to `{case_file}` under a new `## Follow-up: {YYYY-MM-DD}` block (`#2`, `#3` on same-day
+reentry). The investigation is complete when:
+
+- Root cause is Confirmed.
+- Root cause is Hypothesized with a clear data gap.
+- The mental model is sufficient for the user's stated goal (exploration cases).
+- The backlog contains only items requiring unavailable evidence.
+- The user explicitly concludes.

package/src/xmc-skills/4-implementation/xiaoma-investigate/customize.toml

@@ -0,0 +1,62 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-investigate. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run.
+# Use for citation conventions (path:line vs path#L42), grading-scale
+# overrides (ITIL severity 1-5 instead of High/Medium/Low), tone
+# directives (engineering vs exec-facing), or compliance constraints
+# the case file must respect.
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Use ITIL severity 1-5 instead of High/Medium/Low for confidence."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: path to the case-file template, resolved from the skill root.
+# Override to point at an org-shaped template (compliance sections,
+# SLA fields, post-mortem hooks, ITIL fields).
+
+case_file_template = "references/case-file-template.md"
+
+# Scalar: subdirectory under {implementation_artifacts} where case files land.
+# Override for org taxonomies (forensics/, cases/, incidents/, bug-bash/).
+
+case_file_subdir = "investigations"
+
+# Scalar: filename pattern for new case files. {slug} expands to the
+# ticket ID or a short user-agreed name.
+
+case_file_filename = "{slug}-investigation.md"
+
+# Scalar: executed when the workflow finalizes the case file at Outcome 5,
+# after the conclusion is presented. Override wins. Use for post-case
+# automation: post the case to Slack/Teams, push fields back to ticketing,
+# link the case to a sprint, trigger a follow-up retro.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/4-implementation/xiaoma-investigate/references/case-file-template.md

@@ -0,0 +1,127 @@
+# Investigation: {title}
+
+## Hand-off Brief
+
+1. **What happened.** {one-sentence problem statement, evidence-graded}
+2. **Where the case stands.** {status, last finding, what would unblock progress}
+3. **What's needed next.** {single recommended action with rationale}
+
+## Case Info
+
+| Field            | Value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| Ticket           | {ticket-id or "N/A"}                                                       |
+| Date opened      | {date}                                                                     |
+| Status           | Active                                                                     |
+| System           | {OS, version, relevant environment details}                                |
+| Evidence sources | {diagnostic archive, logs, crash dump, code, version control, etc.}        |
+
+## Problem Statement
+
+{User-reported description; the initial claim. May be refined or contradicted by evidence.}
+
+## Evidence Inventory
+
+| Source   | Status                          | Notes     |
+| -------- | ------------------------------- | --------- |
+| {source} | {Available / Partial / Missing} | {details} |
+
+## Investigation Backlog
+
+| # | Path to Explore | Priority              | Status                                | Notes     |
+| - | --------------- | --------------------- | ------------------------------------- | --------- |
+| 1 | {description}   | {High / Medium / Low} | {Open / In Progress / Done / Blocked} | {context} |
+
+## Timeline of Events
+
+| Time        | Event               | Source                | Confidence            |
+| ----------- | ------------------- | --------------------- | --------------------- |
+| {timestamp} | {event description} | {log file, commit, …} | {Confirmed / Deduced} |
+
+## Confirmed Findings
+
+### Finding 1: {title}
+
+**Evidence:** {citation — `path:line`, log timestamp, or commit hash}
+
+**Detail:** {description}
+
+## Deduced Conclusions
+
+### Deduction 1: {title}
+
+**Based on:** {which Confirmed Findings}
+
+**Reasoning:** {logical chain}
+
+**Conclusion:** {what follows}
+
+## Hypothesized Paths
+
+### Hypothesis 1: {title}
+
+**Status:** {Open / Confirmed / Refuted}
+
+**Theory:** {description}
+
+**Supporting indicators:** {what makes this plausible}
+
+**Would confirm:** {specific evidence that would prove this}
+
+**Would refute:** {specific evidence that would disprove this}
+
+**Resolution:** {when Status changes from Open, what evidence settled it}
+
+## Missing Evidence
+
+| Gap              | Impact                               | How to Obtain   |
+| ---------------- | ------------------------------------ | --------------- |
+| {what's missing} | {what it would confirm or eliminate} | {how to get it} |
+
+## Source Code Trace
+
+| Element       | Detail                                      |
+| ------------- | ------------------------------------------- |
+| Error origin  | {file:line, function name}                  |
+| Trigger       | {what causes this code to execute}          |
+| Condition     | {what state produces the observed behavior} |
+| Related files | {other files in the same code path}         |
+
+## Conclusion
+
+**Confidence:** {High / Medium / Low}
+
+{Summary stating what is Confirmed vs. what remains Hypothesized. If a root cause is identified, state it; otherwise
+name the most promising hypothesized paths and what would resolve the remaining uncertainty.}
+
+## Recommended Next Steps
+
+### Fix direction
+
+{What needs to change and why. Categorize by mechanism when multiple issues combine.}
+
+### Diagnostic
+
+{Steps to confirm the root cause: additional logging, targeted tests, data to collect.}
+
+## Reproduction Plan
+
+{Setup, trigger, expected results. Scale from isolated proof to full system reproduction.}
+
+## Side Findings
+
+Tangential observations surfaced during the investigation, evidence-graded, with citation when applicable.
+
+- {observation}
+
+## Follow-up: {date}
+
+### New Evidence
+
+### Additional Findings
+
+### Updated Hypotheses
+
+### Backlog Changes
+
+### Updated Conclusion