@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.0

package/template/.claude/skills/convert-any-to-md/scripts/convert_any_to_md.py

@@ -0,0 +1,487 @@
+#!/usr/bin/env python3
+"""Convert any document (.xlsx, .pdf, .docx, .txt, .csv, .log, .json, .yaml, etc.)
+or a directory of mixed files into clean Markdown, outputting by default into `devflow/reference/`.
+
+Usage:
+    python convert_any_to_md.py <input> [-o OUTPUT] [--recursive]
+
+Arguments:
+    <input>        Path to a single document or a directory.
+    -o, --output   Target output directory (default: devflow/reference).
+    --recursive    Recursively process subdirectories when input is a directory.
+
+Exit codes:
+    0 - All requested conversions succeeded
+    1 - One or more conversions failed (partial success in batch mode)
+    2 - Required dependency missing
+    3 - Invalid input path
+"""
+
+import argparse
+import hashlib
+import posixpath
+import re
+import shutil
+import sys
+import zipfile
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+EXIT_OK = 0
+EXIT_CONVERSION_FAILED = 1
+EXIT_MISSING_DEPENDENCY = 2
+EXIT_INVALID_INPUT = 3
+
+# Namespaces for OOXML
+_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+_MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+_R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+_A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main"
+
+# MarkItDown placeholder pattern for docx
+_PLACEHOLDER_IMAGE_RE = re.compile(
+    r'!\[([^\]]*)\]\(data:image/[a-zA-Z0-9.+-]+;base64[^)]*\)'
+)
+
+# Sheet header pattern for xlsx
+_SHEET_HEADER_RE = re.compile(r"^## (.+)$", re.MULTILINE)
+
+SUPPORTED_TEXT_EXTS = {
+    ".txt", ".log", ".csv", ".tsv", ".json", ".yaml", ".yml",
+    ".md", ".markdown", ".py", ".js", ".ts", ".html", ".xml", ".css"
+}
+
+IGNORE_EXTS = {
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".zip", ".tar", ".gz",
+    ".7z", ".rar", ".iso", ".pyc", ".class", ".o", ".obj"
+}
+
+def get_markitdown():
+    """Lazy import MarkItDown if available."""
+    try:
+        from markitdown import MarkItDown
+        return MarkItDown()
+    except ImportError:
+        return None
+
+# ============================================================================
+# Excel Handler
+# ============================================================================
+
+def _normalize_rel_path(base_dir: str, target: str) -> str:
+    if target.startswith("/"):
+        return target.lstrip("/")
+    return posixpath.normpath(posixpath.join(base_dir, target))
+
+def _xlsx_sheet_media(xlsx_path: Path):
+    try:
+        with zipfile.ZipFile(xlsx_path) as z:
+            names = set(z.namelist())
+            if "xl/workbook.xml" not in names or "xl/_rels/workbook.xml.rels" not in names:
+                return {}
+            workbook_xml = z.read("xl/workbook.xml")
+            workbook_rels_xml = z.read("xl/_rels/workbook.xml.rels")
+
+            sheet_rid = {}
+            for sheet_el in ET.fromstring(workbook_xml).iter(f"{{{_MAIN_NS}}}sheet"):
+                name = sheet_el.get("name")
+                rid = sheet_el.get(f"{{{_R_NS}}}id")
+                if name and rid:
+                    sheet_rid[name] = rid
+
+            rid_target = {}
+            for rel in ET.fromstring(workbook_rels_xml).findall(f"{{{_REL_NS}}}Relationship"):
+                rid_target[rel.get("Id")] = rel.get("Target")
+
+            result = {}
+            for sheet_name, rid in sheet_rid.items():
+                target = rid_target.get(rid)
+                if not target:
+                    continue
+                sheet_path = _normalize_rel_path("xl", target)
+                if sheet_path not in names or "/" not in sheet_path:
+                    continue
+                sheet_dir, sheet_file = sheet_path.rsplit("/", 1)
+                sheet_rels_path = f"{sheet_dir}/_rels/{sheet_file}.rels"
+                if sheet_rels_path not in names:
+                    continue
+
+                drawing_rid = None
+                for d in ET.fromstring(z.read(sheet_path)).iter(f"{{{_MAIN_NS}}}drawing"):
+                    drawing_rid = d.get(f"{{{_R_NS}}}id")
+                    break
+                if not drawing_rid:
+                    continue
+
+                drawing_target = None
+                for rel in ET.fromstring(z.read(sheet_rels_path)).findall(f"{{{_REL_NS}}}Relationship"):
+                    if rel.get("Id") == drawing_rid:
+                        drawing_target = rel.get("Target")
+                        break
+                if not drawing_target:
+                    continue
+                drawing_path = _normalize_rel_path(sheet_dir, drawing_target)
+                if drawing_path not in names or "/" not in drawing_path:
+                    continue
+                drawing_dir, drawing_file = drawing_path.rsplit("/", 1)
+                drawing_rels_path = f"{drawing_dir}/_rels/{drawing_file}.rels"
+                if drawing_rels_path not in names:
+                    continue
+
+                drawing_rel_map = {}
+                for rel in ET.fromstring(z.read(drawing_rels_path)).findall(f"{{{_REL_NS}}}Relationship"):
+                    drawing_rel_map[rel.get("Id")] = rel.get("Target")
+
+                media_paths = []
+                for blip in ET.fromstring(z.read(drawing_path)).iter(f"{{{_A_NS}}}blip"):
+                    embed_rid = blip.get(f"{{{_R_NS}}}embed")
+                    if not embed_rid:
+                        continue
+                    rel_target = drawing_rel_map.get(embed_rid)
+                    if not rel_target:
+                        continue
+                    media_path = _normalize_rel_path(drawing_dir, rel_target)
+                    if media_path in names:
+                        media_paths.append(media_path)
+
+                if media_paths:
+                    result[sheet_name] = media_paths
+            return result
+    except Exception:
+        return {}
+
+def extract_xlsx_images(xlsx_path: Path, img_dir: Path):
+    sheet_media = _xlsx_sheet_media(xlsx_path)
+    if not sheet_media:
+        return {}
+
+    written = {}
+    with zipfile.ZipFile(xlsx_path) as z:
+        names_in_zip = set(z.namelist())
+        for sheet_idx, (sheet_name, media_paths) in enumerate(sheet_media.items(), start=1):
+            safe_name = re.sub(r"[^A-Za-z0-9_.-]+", "_", sheet_name).strip("_") or "sheet"
+            safe_prefix = f"sheet{sheet_idx:03d}_{safe_name}"
+            files = []
+            for idx, media_path in enumerate(media_paths, start=1):
+                if media_path not in names_in_zip:
+                    continue
+                ext = Path(media_path).suffix.lstrip(".").lower() or "bin"
+                if ext == "jpg":
+                    ext = "jpeg"
+                fname = f"{safe_prefix}_img{idx:03d}.{ext}"
+                dest = img_dir / fname
+                img_dir.mkdir(parents=True, exist_ok=True)
+                with z.open(media_path) as src, open(dest, "wb") as dst:
+                    shutil.copyfileobj(src, dst)
+                files.append(fname)
+            if files:
+                written[sheet_name] = files
+    return written
+
+def convert_excel(file_path: Path, out_dir: Path, md_engine) -> bool:
+    img_dir = out_dir / "img"
+    sheet_images = extract_xlsx_images(file_path, img_dir)
+    
+    if md_engine:
+        res = md_engine.convert(str(file_path))
+        text = res.text_content
+    else:
+        text = f"# {file_path.stem}\n\n*(MarkItDown engine not available. Basic conversion applied)*\n"
+
+    if sheet_images:
+        matches = list(_SHEET_HEADER_RE.finditer(text))
+        if matches:
+            parts = []
+            last_end = 0
+            for i, m in enumerate(matches):
+                sheet_name = m.group(1).strip()
+                next_start = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+                section = text[last_end:next_start]
+                last_end = next_start
+
+                if sheet_name in sheet_images:
+                    img_lines = ["\n\n#### Images in this sheet\n"]
+                    for fname in sheet_images[sheet_name]:
+                        img_lines.append(f"![{sheet_name} image](img/{fname})\n")
+                    section = section.rstrip() + "\n" + "".join(img_lines)
+                parts.append(section)
+            text = "".join(parts)
+
+    out_md = out_dir / f"{file_path.stem}.md"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_md.write_text(text, encoding="utf-8")
+    return True
+
+# ============================================================================
+# PDF Handler
+# ============================================================================
+
+def extract_pdf_images(pdf_path: Path, img_dir: Path):
+    try:
+        import fitz
+    except ImportError:
+        return {}
+
+    written_by_page = {}
+    try:
+        doc = fitz.open(str(pdf_path))
+    except Exception:
+        return written_by_page
+
+    try:
+        for page_index in range(len(doc)):
+            page = doc[page_index]
+            page_label = page_index + 1
+            raw_images = []
+            try:
+                xobjects = page.get_images(full=True)
+            except Exception:
+                xobjects = []
+
+            for img in xobjects:
+                xref = img[0]
+                try:
+                    base_image = doc.extract_image(xref)
+                except Exception:
+                    continue
+                img_bytes = base_image.get("image") or b""
+                if not img_bytes:
+                    continue
+                ext = (base_image.get("ext") or "png").lower()
+                raw_images.append((img_bytes, ext))
+
+            if not raw_images:
+                continue
+
+            saved_files = []
+            img_dir.mkdir(parents=True, exist_ok=True)
+            for idx, (img_bytes, ext) in enumerate(raw_images, start=1):
+                fname = f"page{page_label:03d}_img{idx:03d}.{ext}"
+                dest = img_dir / fname
+                dest.write_bytes(img_bytes)
+                saved_files.append(fname)
+
+            if saved_files:
+                written_by_page[page_label] = saved_files
+    finally:
+        doc.close()
+    return written_by_page
+
+def convert_pdf(file_path: Path, out_dir: Path, md_engine) -> bool:
+    img_dir = out_dir / "img"
+    page_images = extract_pdf_images(file_path, img_dir)
+
+    if md_engine:
+        res = md_engine.convert(str(file_path))
+        text = res.text_content
+    else:
+        text = f"# {file_path.stem}\n\n*(MarkItDown engine not available)*\n"
+
+    if page_images:
+        appendix = ["\n\n## Extracted Images\n"]
+        for page_num in sorted(page_images.keys()):
+            appendix.append(f"\n### Page {page_num}\n")
+            for fname in page_images[page_num]:
+                appendix.append(f"![Page {page_num} image](img/{fname})\n")
+        text = text.rstrip() + "".join(appendix)
+
+    out_md = out_dir / f"{file_path.stem}.md"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_md.write_text(text, encoding="utf-8")
+    return True
+
+# ============================================================================
+# Word Handler
+# ============================================================================
+
+def _word_ordered_media(docx_path: Path):
+    try:
+        with zipfile.ZipFile(docx_path) as z:
+            if "word/document.xml" not in z.namelist() or "word/_rels/document.xml.rels" not in z.namelist():
+                return []
+            rels_xml = z.read("word/_rels/document.xml.rels")
+            doc_xml = z.read("word/document.xml")
+    except Exception:
+        return []
+
+    try:
+        rels_root = ET.fromstring(rels_xml)
+        doc_root = ET.fromstring(doc_xml)
+    except Exception:
+        return []
+
+    rel_map = {rel.get("Id"): rel.get("Target") for rel in rels_root.findall(f"{{{_REL_NS}}}Relationship")}
+    ordered_rel_ids = []
+    for elem in doc_root.iter():
+        tag = elem.tag.rsplit("}", 1)[-1]
+        rid = elem.get(f"{{{_R_NS}}}embed") if tag == "blip" else (elem.get(f"{{{_R_NS}}}id") if tag == "imagedata" else None)
+        if rid:
+            ordered_rel_ids.append(rid)
+
+    ordered_media = []
+    for rid in ordered_rel_ids:
+        target = rel_map.get(rid)
+        if not target or "media/" not in target:
+            continue
+        media_path = target.lstrip("/") if target.startswith("/") else posixpath.normpath(target if target.startswith("word/") else posixpath.join("word", target))
+        ordered_media.append((rid, media_path))
+    return ordered_media
+
+def extract_word_images(docx_path: Path, img_dir: Path):
+    ordered_media = _word_ordered_media(docx_path)
+    if not ordered_media:
+        return []
+
+    written = []
+    with zipfile.ZipFile(docx_path) as z:
+        names_in_zip = set(z.namelist())
+        for idx, (rid, media_path) in enumerate(ordered_media, start=1):
+            if media_path not in names_in_zip:
+                continue
+            ext = Path(media_path).suffix.lstrip(".").lower() or "bin"
+            if ext == "jpg":
+                ext = "jpeg"
+            fname = f"img{idx:03d}.{ext}"
+            dest = img_dir / fname
+            img_dir.mkdir(parents=True, exist_ok=True)
+            with z.open(media_path) as src, open(dest, "wb") as dst:
+                shutil.copyfileobj(src, dst)
+            written.append(fname)
+    return written
+
+def convert_word(file_path: Path, out_dir: Path, md_engine) -> bool:
+    img_dir = out_dir / "img"
+    images = extract_word_images(file_path, img_dir)
+
+    if md_engine:
+        res = md_engine.convert(str(file_path))
+        text = res.text_content
+    else:
+        text = f"# {file_path.stem}\n\n*(MarkItDown engine not available)*\n"
+
+    if images:
+        img_idx = 0
+        def replace_img(match):
+            nonlocal img_idx
+            alt_text = match.group(1)
+            if img_idx < len(images):
+                fname = images[img_idx]
+                img_idx += 1
+                return f"![{alt_text}](img/{fname})"
+            return match.group(0)
+
+        text = _PLACEHOLDER_IMAGE_RE.sub(replace_img, text)
+
+    out_md = out_dir / f"{file_path.stem}.md"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_md.write_text(text, encoding="utf-8")
+    return True
+
+# ============================================================================
+# Plaintext Handler
+# ============================================================================
+
+def convert_text(file_path: Path, out_dir: Path) -> bool:
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="replace")
+    except Exception as exc:
+        print(f"ERROR reading {file_path}: {exc}", file=sys.stderr)
+        return False
+
+    ext = file_path.suffix.lower()
+    if ext in {".md", ".markdown"}:
+        md_text = content
+    else:
+        lang_map = {
+            ".py": "python", ".js": "javascript", ".ts": "typescript",
+            ".json": "json", ".yaml": "yaml", ".yml": "yaml",
+            ".html": "html", ".xml": "xml", ".css": "css", ".csv": "csv"
+        }
+        lang = lang_map.get(ext, "")
+        if lang:
+            md_text = f"# {file_path.name}\n\n```{lang}\n{content}\n```\n"
+        else:
+            md_text = f"# {file_path.name}\n\n{content}\n"
+
+    out_md = out_dir / f"{file_path.stem}.md"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_md.write_text(md_text, encoding="utf-8")
+    return True
+
+# ============================================================================
+# Main Router
+# ============================================================================
+
+def convert_single_file(file_path: Path, base_out_dir: Path, md_engine) -> bool:
+    ext = file_path.suffix.lower()
+    out_dir = base_out_dir / file_path.stem
+
+    if ext in IGNORE_EXTS:
+        return True
+
+    print(f"Converting [{ext or 'text'}] {file_path.name} -> {out_dir}")
+
+    if ext == ".xlsx":
+        return convert_excel(file_path, out_dir, md_engine)
+    elif ext == ".pdf":
+        return convert_pdf(file_path, out_dir, md_engine)
+    elif ext == ".docx":
+        return convert_word(file_path, out_dir, md_engine)
+    elif ext in SUPPORTED_TEXT_EXTS or ext == "":
+        return convert_text(file_path, out_dir)
+    else:
+        # Fallback to text conversion for unknown extensions
+        return convert_text(file_path, out_dir)
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert documents to Markdown and save to devflow/reference/"
+    )
+    parser.add_argument("input", help="Path to a file or directory to convert")
+    parser.add_argument(
+        "-o", "--output",
+        default="devflow/reference",
+        help="Target output directory (default: devflow/reference)"
+    )
+    parser.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Recursively process subdirectories"
+    )
+
+    args = parser.parse_args()
+    input_path = Path(args.input).resolve()
+    base_out_dir = Path(args.output).resolve()
+
+    if not input_path.exists():
+        print(f"ERROR: Input path not found: {input_path}", file=sys.stderr)
+        sys.exit(EXIT_INVALID_INPUT)
+
+    md_engine = get_markitdown()
+
+    if input_path.is_file():
+        success = convert_single_file(input_path, base_out_dir, md_engine)
+        sys.exit(EXIT_OK if success else EXIT_CONVERSION_FAILED)
+    elif input_path.is_dir():
+        pattern = "**/*" if args.recursive else "*"
+        files = [p for p in input_path.glob(pattern) if p.is_file()]
+        
+        if not files:
+            print(f"No files found in {input_path}")
+            sys.exit(EXIT_OK)
+
+        success_count = 0
+        fail_count = 0
+        for f in files:
+            if f.suffix.lower() in IGNORE_EXTS:
+                continue
+            if convert_single_file(f, base_out_dir, md_engine):
+                success_count += 1
+            else:
+                fail_count += 1
+
+        print(f"\nBatch summary: {success_count} succeeded, {fail_count} failed.")
+        sys.exit(EXIT_OK if fail_count == 0 else EXIT_CONVERSION_FAILED)
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/convert-any-to-md/scripts/requirements.txt

@@ -0,0 +1,3 @@
+markitdown[xlsx]
+pymupdf
+openpyxl

package/template/.claude/skills/debug/SKILL.md

@@ -1,70 +1,145 @@
 ---
 name: debug
-description: "[Devflow] Root cause investigation and diagnostic loop before or during implementation without editing code. Use when encountering broken behavior, test failures, or bugs."
+description: "[devflow][B] Diagnose a failing test, broken build, crash, error, regression, or unexpected behavior without editing source or Blueprint state. Reproduces the symptom with the smallest safe command, localizes the failing path, tests competing hypotheses, identifies the root cause when evidence supports one, and reports a repair handoff to /fix or /implement. Use when the user runs /debug, invokes $debug, asks why something is failing or broken, wants a root-cause investigation, or asks to diagnose before fixing."
 ---
 
-# Debug & Root Cause Analysis (RCA)
+# debug - find the cause before changing the code
 
-## Overview
+Where this sits in the workflow:
 
-This is the comprehensive debugging master skill for Nexus-DevFlow. It guides systematic root-cause investigation without blindly editing code. The goal is to find the actual origin of an issue, not merely suppress visible symptoms.
+    reported failure  ->  [debug]  ->  /fix or /implement
+    (test, build,          (reproduce,    (spec a new fix, or
+     crash, behavior)       isolate,       repair active work)
+                            explain)
 
-**The Debug Mantra (9arm Pattern)**:
-```text
-Reproduce ➔ Trace Fail Path ➔ Falsify Hypotheses ➔ Cross-reference Breadcrumbs ➔ RCA Proof
-```
+`/debug` separates diagnosis from repair. It gathers evidence, narrows the
+failure to a specific cause when possible, and stops with a useful handoff. It
+does not make the code "temporarily work" while investigating.
 
----
+## Input
 
-## 1. The 4-Phase Diagnostic Loop
+Accept a symptom, failing command, error message, or unexpected behavior. Examples:
 
-### Phase 1: Reproduce & Classify
-- Restate the observed symptom vs. expected behavior with exact steps.
-- Create a minimal reproduction script, test case, or curl command.
-- Rule: **Do not propose a code fix before the reproduction story is verified.**
+    /debug npm test fails in cart-total.test.js
+    /debug the upload route returns 500 for PNG files
+    /debug why does the production build fail?
 
-### Phase 2: Isolate & Hypothesize
-- Generate 2–4 distinct hypotheses ranked by probability.
-- Formulate specific criteria and evidence that would *falsify* each hypothesis.
+With no useful symptom, ask for the expected behavior, actual behavior, and
+smallest known reproduction. Do not guess which problem the user means.
 
-### Phase 3: Non-Destructive Investigation
-- Trace code execution paths end-to-end (stack traces, logs, variable states, async boundaries).
-- Inspect recent commits or configuration changes that touch the affected boundary.
-- Test hypotheses methodically using tests and logging without altering business logic.
+## Step 1 - establish the boundary
 
-### Phase 4: Root Cause Conclusion (RCA)
-- State precisely *why* the bug occurred (underlying invariant violation).
-- Define the minimal, robust architectural fix direction.
-- Propose regression prevention measures (unit test, type guard, linter rule).
+Read the project instructions and the context relevant to the failure:
 
----
+- `AGENTS.md` and its real commands
+- `devflow/context/project-overview.md`
+- `devflow/context/coding-standards.md`
+- `devflow/context/current-feature.md`
+- the reported error, failing output, and affected files
+- git status, diff, and recent log when a regression is possible
 
-## 2. Output Format (RCA Report)
+State the symptom and what would count as reproducing it. Note whether the
+failure belongs to an active feature or is an unplanned bug.
 
-Save substantial RCA investigations under:
-```text
-devflow/debug/rca-{slug}.md
-```
+Do not treat a dirty working tree as permission to discard or rewrite anything.
+Use the diff as evidence and preserve it.
 
-Structure:
-```markdown
-## Debug Summary
+## Step 2 - reproduce safely
 
-1. **Symptom**: [What is happening vs expected]
-2. **Evidence**: [Error logs, stack trace, file:line references]
-3. **Investigation Path**: [Hypotheses tested and falsification proof]
-4. **Root Cause**: [The exact mechanism causing the failure]
-5. **Fix Direction**: [Recommended scoped change]
-6. **Regression Guard**: [Reproduction test to add before fixing]
-```
+Run the smallest existing command or interaction that can reproduce the symptom.
 
----
+- Prefer one focused test, request, CLI command, or input over the entire suite.
+- Capture the exact exit code, error, stack trace, output, response, console
+  error, or failed request.
+- Reuse an already-running local app when available. If reproduction requires a
+  long-running server that is not running, ask the user to start it and provide
+  the documented command.
+- Do not install dependencies, change configuration, run migrations, mutate
+  production data, contact external users, or use destructive commands to force
+  a reproduction.
+- Do not edit code to add logs or probes. Use existing logs, debuggers,
+  read-only inspection, or one-off commands that do not change project files.
+- Compare git status after diagnostic commands. If one changes tracked or
+  untracked project files, stop and report those paths. Do not clean, restore,
+  or hide the changes.
+
+If the symptom cannot be reproduced, say what was attempted and what evidence is
+missing. Continue with static investigation only when it can produce a clearly
+labeled hypothesis, not a claimed root cause.
+
+## Step 3 - localize the failure
+
+Trace from the observed failure toward the smallest responsible area.
+
+Use the evidence that fits the project:
+
+- the first relevant application frame in a stack trace
+- the smallest failing test and its inputs
+- request and response data at the failing boundary
+- console and network errors
+- callers, imports, data flow, and configuration reads
+- `git diff`, `git log`, and `git blame` for a suspected regression
+- comparison with a nearby working path or input
+
+Separate facts from hypotheses. Test the cheapest safe competing explanations
+first. Do not stop at the first plausible line, blame a dependency without
+evidence, or confuse the place an error surfaced with the place it originated.
+
+## Step 4 - confirm or narrow
+
+A root cause is confirmed only when the evidence connects all three:
+
+1. the triggering input or state
+2. the responsible code, configuration, or contract
+3. the observed failure
+
+When safe and read-only, vary one input or run a smaller focused command to
+confirm the connection. Do not change implementation or tests to prove the fix.
+
+Use one of these verdicts:
+
+- **Confirmed** - evidence identifies the cause and explains the failure.
+- **Likely** - evidence narrows the cause, but one specific proof is unavailable.
+- **Blocked** - the failure cannot be reproduced or required evidence is
+  inaccessible.
+
+## Step 5 - report and hand off
+
+Give a concise debug report:
+
+- symptom and reproduction
+- verdict
+- root cause or leading hypothesis
+- evidence, including commands and relevant paths
+- affected behavior and likely repair boundary
+- what was not verified
+- exact next action
+
+Choose the next action without writing files:
+
+- Active feature or fix caused the failure -> return the diagnosis to
+  `/implement`.
+- No active work item and the bug is confirmed -> recommend
+  `/fix "<concise bug and confirmed cause>"`.
+- Cause is only likely or blocked -> recommend the next diagnostic evidence, not
+  a speculative repair.
+- The issue is planned product work rather than a defect -> point to
+  `/feature`.
 
-## Relationship To DevFlow 2.0
+## Rules
+
+- Diagnose, do not repair. Never edit source, tests, configuration, lockfiles, or
+  Blueprint files.
+- Never create, switch, merge, or delete branches. Never commit or push.
+- Do not update the findings ledger. `/audit` owns recorded code-quality
+  findings; `/debug` reports one investigated failure in chat.
+- Evidence outranks confidence. Label uncertainty and failed reproduction
+  honestly.
+- Preserve the user's working tree and running processes.
+- Do not broaden one failure into a general audit or refactor.
 
-- **Classification**: Companion command & Investigation lane
-- **Mainline integration**:
-  - During `00-explore`: Unclear failure intake before allocation
-  - During `40-execute`: Hard test failure or unexpected runtime exception
-  - During `50-verify`: Defect found during QA inspection
-- **Handoff**: `test` (write repro test), `40-execute` (execute fix), `50-verify` (re-check)
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown with a short
+evidence list and a clear next action.