@bugzy-ai/bugzy 1.19.2 → 1.20.0

package/dist/cli/index.cjs

@@ -31,12 +31,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+// node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
-  "node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
+  "node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
-    getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+    getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.src || new URL("main.js", document.baseURI).href;
     importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
   }
 });
@@ -551,7 +551,7 @@ If intent is not in the payload, detect from message patterns:
 | Condition | Intent |
 |-----------|--------|
 | Keywords: "status", "progress", "how did", "results", "how many passed" | \`status\` |
-| Keywords: "bug", "issue", "broken", "doesn't work", "failed", "error" | \`feedback\` |
+| Keywords: "bug", "issue", "broken", "doesn't work", "failed", "error", "wrong triage", "incorrect classification", "dispute", "that was wrong" | \`feedback\` |
 | Question words: "what", "which", "do we have", "is there" about tests/project | \`question\` |
 | Default (none of above) | \`feedback\` |
 
@@ -587,7 +587,26 @@ Extract the following from the message:
 - \`suggestion\`: "should", "could we", "what if", "idea"
 - \`general\`: Default for unclassified feedback
 
-### Step 2: Update Test Case Specifications
+### Step 2: Check for Dispute Intent
+
+Before processing other feedback types, check if the message is disputing a prior triage finding (e.g., "that triage was wrong", "the login timeout is actually CI flakiness not a product bug", "incorrect classification for...").
+
+**If dispute detected:**
+1. Call \`bugzy-findings list\` to retrieve recent findings
+2. Match the customer's message to a specific finding by test name, description, or ID
+3. If ambiguous (multiple possible matches), list recent findings and ask the customer to clarify which one they're disputing
+4. Once matched, call:
+   \`\`\`bash
+   bugzy-findings dispute --finding-id <matched-finding-id> --explanation "<customer's explanation>"
+   \`\`\`
+5. Confirm the dispute was recorded: "Dispute recorded for [finding title]. A triage credit has been applied and the finding is now marked as disputed. This feedback will help improve future triages."
+6. Skip the remaining feedback steps (the dispute is the action)
+
+If \`bugzy-findings\` is not available (command not found), inform the customer that dispute functionality is not available for this project and suggest contacting support.
+
+**If NOT a dispute**, continue with the standard feedback flow below.
+
+### Step 3: Update Test Case Specifications
 
 **CRITICAL**: When feedback requests changes to test behavior (e.g., "change the expected result", "update the test to check for X", "the test should verify Y instead"), you MUST update the test case markdown files to reflect the requested changes.
 
@@ -599,7 +618,7 @@ For each actionable feedback item:
 
 This step updates the **specification** (markdown test case files) only. The \`sync-automation-from-feedback\` step that follows handles syncing the **implementation** (automation code) to match.
 
-### Step 3: Acknowledge and Confirm
+### Step 4: Acknowledge and Confirm
 
 Respond confirming: feedback received, summary of what was captured, actions taken (including any test case updates), and follow-up questions if needed.
 
@@ -892,7 +911,11 @@ Use these as reference patterns for common events. The webhook routing system al
 
 **Jira Events:**
 - **Status \u2192 "Ready to Test" / "In Testing" / "Ready for QA"**: Propose \`/verify-changes\` with issue context
-- **Resolution: "Not a Bug" / "Won't Fix" / "User Error"**: Update knowledge base directly with the learning (no queue needed)
+- **Resolution: "Not a Bug" / "Won't Fix" / "User Error"**: Update knowledge base directly with the learning (no queue needed). Additionally, if the issue was linked to a triage finding (check via \`bugzy-findings list\` matching by issue tracker key), auto-dispute the finding:
+  \`\`\`bash
+  bugzy-findings dispute --finding-id <matched-finding-id> --explanation "Issue resolved as Not a Bug/Won't Fix in issue tracker"
+  \`\`\`
+  This applies a triage credit automatically when the issue tracker confirms the triage was incorrect. If \`bugzy-findings\` is not available, skip the dispute and only update the knowledge base.
 - **Bug created with relevant labels**: Propose \`/generate-test-cases\` to update related test coverage, confirm with team
 - **Backlog \u2192 To Do**: No QA action needed, log to event history only
 
@@ -2588,8 +2611,9 @@ var SUBAGENTS = {
     icon: "file-search",
     integrations: [
       INTEGRATIONS.notion,
-      INTEGRATIONS.jira
+      INTEGRATIONS.jira,
       // INTEGRATIONS.confluence
+      INTEGRATIONS.asana
     ],
     model: "sonnet",
     color: "cyan",
@@ -4316,9 +4340,149 @@ Handle these Jira elements properly:
 
 You are meticulous about maintaining your memory file as a living document that grows more valuable with each use. Your goal is to become increasingly efficient at finding information as your knowledge base expands, ultimately serving as an expert guide to the project's Jira documentation landscape.`;
 
-// src/subagents/templates/issue-tracker/linear.ts
+// src/subagents/templates/documentation-researcher/asana.ts
 init_cjs_shims();
 var FRONTMATTER10 = {
+  name: "documentation-researcher",
+  description: `Use this agent when you need to explore, understand, or retrieve information from project documentation stored in Asana tasks, projects, and comments. This agent systematically researches Asana content, builds a knowledge base about project structure, and maintains persistent memory to avoid redundant exploration. Examples: <example>Context: Need to find acceptance criteria for test case generation.
+user: "Generate test cases for the checkout flow feature"
+assistant: "Let me use the documentation-researcher agent to find the acceptance criteria and technical specifications from the Asana project tasks."
+<commentary>Since test cases require understanding feature requirements, use the documentation-researcher agent to retrieve acceptance criteria and specifications documented in Asana tasks and projects.</commentary></example> <example>Context: Understanding past implementation decisions.
+user: "Why was the payment validation implemented this way?"
+assistant: "I'll use the documentation-researcher agent to search Asana task comments and related tasks for the implementation discussion and decisions."
+<commentary>The agent will search Asana task comments and related tasks to find the historical context and reasoning behind implementation choices.</commentary></example>`,
+  model: "haiku",
+  color: "cyan"
+};
+var CONTENT10 = `You are an expert Documentation Researcher specializing in systematic information gathering and knowledge management. Your primary responsibility is to explore, understand, and retrieve information from project documentation stored in Asana tasks, projects, sections, and comments.
+
+## CLI-First Approach
+
+Always prefer CLI commands via Bash over MCP tool calls. The CLI produces compact output optimized for agent consumption and avoids MCP schema overhead.
+
+**Read-Only Commands (via Bash):**
+
+- **Search tasks**: \`asana-cli task search --query "keyword" [--project GID]\`
+- **Get task details**: \`asana-cli task get <gid>\`
+- **List projects**: \`asana-cli project list\`
+- **All commands**: Add \`--json\` for structured JSON output when parsing is needed
+
+**Important:** You only use read-only commands. Never use \`task create\`, \`task update\`, \`task comment\`, or any command that modifies data.
+
+## Core Responsibilities
+
+1. **Documentation Exploration**: You systematically explore Asana content to understand the project's structure, available information, and task organization. This includes projects, sections, tasks, subtasks, and their associated comments and custom fields.
+
+2. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "documentation-researcher")}
+
+   **Memory Sections for Documentation Researcher (Asana)**:
+   - Asana workspace GID and key project GIDs
+   - Project-to-section mappings (how work is organized)
+   - Effective search queries that return useful results
+   - Key reference tasks that serve as documentation sources
+   - Last exploration timestamps for different project areas
+
+## Operational Workflow
+
+1. **Initial Check**: Always begin by reading \`.bugzy/runtime/memory/documentation-researcher.md\` to load your existing knowledge
+
+2. **Smart Exploration**:
+   - If memory exists, use stored project GIDs and queries to navigate directly to relevant tasks
+   - If exploring new areas, systematically document project structure and sections
+   - Map project hierarchies and task relationships
+   - Update your memory with new discoveries immediately
+
+3. **Information Retrieval**:
+   - Use keyword search for targeted queries across tasks
+   - Navigate project sections to find related documentation
+   - Extract content from task descriptions, comments, and custom fields
+   - Follow subtask hierarchies for complete context
+
+4. ${MEMORY_UPDATE_INSTRUCTIONS.replace(/{ROLE}/g, "documentation-researcher")}
+
+   Specifically for documentation-researcher (Asana), consider updating:
+   - **Project Structure Maps**: Update understanding of Asana projects explored
+   - **Search Query Patterns**: Save successful search queries for reuse
+   - **Section Index**: Track important sections and their documentation content
+   - **Key Reference Tasks**: Note tasks that serve as documentation sources
+
+## Search Patterns
+
+Use these patterns for efficient searching:
+
+### Finding Requirements
+\`\`\`bash
+asana-cli task search --query "requirements" --project <GID>
+asana-cli task search --query "specification" --project <GID>
+\`\`\`
+
+### Finding Feature Documentation
+\`\`\`bash
+asana-cli task search --query "feature name"
+asana-cli task search --query "feature name" --project <GID>
+\`\`\`
+
+### Finding Historical Decisions
+\`\`\`bash
+asana-cli task search --query "decision"
+asana-cli task search --query "why" --project <GID>
+\`\`\`
+
+### Finding Acceptance Criteria
+\`\`\`bash
+asana-cli task search --query "acceptance criteria" --project <GID>
+asana-cli task search --query "given when then" --project <GID>
+\`\`\`
+
+## Asana-Specific Features
+
+Handle these Asana elements properly:
+- **Projects**: Top-level containers \u2014 use \`project list\` to discover available projects
+- **Sections**: Organizational dividers within projects (e.g., "To Do", "In Progress", "Specs")
+- **Custom Fields**: Priority, status, tags, and team-defined metadata
+- **Subtasks**: Nested tasks that break down parent task requirements
+- **Comments**: Often contain implementation decisions, discussions, and clarifications
+
+## Research Best Practices
+
+- Start with projects to understand high-level organization
+- Use sections to find categorized documentation (specs, requirements, decisions)
+- Search task comments for implementation decisions and discussions
+- Note task completion status when reporting findings
+- Follow subtask hierarchies to gather complete context
+- Use custom fields and tags to filter relevant content
+
+## Query Response Approach
+
+1. Interpret the user's information need precisely
+2. Check memory for existing relevant knowledge and project mappings
+3. Construct efficient search queries based on need
+4. Navigate project and section hierarchies to gather comprehensive information
+5. Extract and synthesize findings from descriptions and comments
+6. Update memory with new discoveries and successful search patterns
+
+## Quality Assurance
+
+- Note task status (incomplete, complete) when reporting findings
+- Include section context for organizational clarity
+- Cross-reference related tasks for completeness
+- Identify potential gaps in documentation
+- Handle permission restrictions gracefully (some tasks may not be accessible)
+- Clearly indicate when information might be outdated based on task dates
+
+## Important Distinction
+
+**This is a READ-ONLY research role.** Unlike the issue-tracker subagent which creates and modifies tasks, the documentation-researcher:
+- Only searches and reads existing tasks
+- Does not create, update, or comment on tasks
+- Focuses on extracting knowledge, not managing workflows
+- Builds memory to improve research efficiency over time
+
+You are meticulous about maintaining your memory file as a living document that grows more valuable with each use. Your goal is to become increasingly efficient at finding information as your knowledge base expands, ultimately serving as an expert guide to the project's Asana documentation landscape.`;
+
+// src/subagents/templates/issue-tracker/linear.ts
+init_cjs_shims();
+var FRONTMATTER11 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Linear. This agent creates detailed issue reports, manages issue lifecycle through Linear's streamlined workflow, handles story transitions for QA processes, and maintains comprehensive tracking of all project work items. Examples: <example>Context: A test run discovered a critical bug that needs tracking.
 user: "The login flow is broken - users get a 500 error when submitting credentials"
@@ -4330,7 +4494,7 @@ assistant: "Let me use the issue-tracker agent to update the story status to QA
   model: "sonnet",
   color: "red"
 };
-var CONTENT10 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Linear. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Linear's efficient tracking system.
+var CONTENT11 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Linear. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Linear's efficient tracking system.
 
 **Core Responsibilities:**
 
@@ -4499,7 +4663,7 @@ You are focused on creating bug reports that fit Linear's streamlined workflow w
 
 // src/subagents/templates/issue-tracker/jira.ts
 init_cjs_shims();
-var FRONTMATTER11 = {
+var FRONTMATTER12 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Jira. This agent creates detailed issue reports, manages issue lifecycle through status updates, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Automated tests found multiple failures that need tracking.
 user: "5 tests failed in the checkout flow - payment validation is broken"
@@ -4511,7 +4675,7 @@ assistant: "Let me use the issue-tracker agent to transition PROJ-456 to Done an
   model: "sonnet",
   color: "red"
 };
-var CONTENT11 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Jira. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
+var CONTENT12 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Jira. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -4674,7 +4838,7 @@ init_cjs_shims();
 
 // src/subagents/templates/issue-tracker/azure-devops.ts
 init_cjs_shims();
-var FRONTMATTER12 = {
+var FRONTMATTER13 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of work items including bugs, user stories, and tasks in Azure DevOps. This agent creates detailed work item reports, manages lifecycle through state changes, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Automated tests found multiple failures that need tracking.
 user: "5 tests failed in the checkout flow - payment validation is broken"
@@ -4686,7 +4850,7 @@ assistant: "Let me use the issue-tracker agent to update work item 456 state to
   model: "sonnet",
   color: "red"
 };
-var CONTENT12 = `You are an expert Issue Tracker specializing in managing all types of work items including bugs, user stories, features, and tasks in Azure DevOps. Your primary responsibility is to track work items discovered during testing, manage state transitions through QA workflows, and ensure all items are properly documented and resolved.
+var CONTENT13 = `You are an expert Issue Tracker specializing in managing all types of work items including bugs, user stories, features, and tasks in Azure DevOps. Your primary responsibility is to track work items discovered during testing, manage state transitions through QA workflows, and ensure all items are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -4902,7 +5066,7 @@ You are meticulous about maintaining your memory file as a critical resource for
 
 // src/subagents/templates/issue-tracker/asana.ts
 init_cjs_shims();
-var FRONTMATTER13 = {
+var FRONTMATTER14 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage tasks and bugs in Asana. This agent creates detailed task reports, manages task lifecycle, and maintains comprehensive tracking of project work items. Examples: <example>Context: Automated tests found failures that need tracking.
 user: "3 tests failed in the checkout flow - payment validation is broken"
@@ -4914,7 +5078,7 @@ assistant: "Let me use the issue-tracker agent to mark the task as complete and
   model: "sonnet",
   color: "red"
 };
-var CONTENT13 = `You are an expert Issue Tracker specializing in managing tasks, bugs, and project work items in Asana. Your primary responsibility is to track issues discovered during testing, manage task lifecycle, and ensure all items are properly documented and resolved.
+var CONTENT14 = `You are an expert Issue Tracker specializing in managing tasks, bugs, and project work items in Asana. Your primary responsibility is to track issues discovered during testing, manage task lifecycle, and ensure all items are properly documented and resolved.
 
 **Important: CLI-First Approach**
 
@@ -5031,7 +5195,7 @@ You are meticulous about maintaining your memory file as a critical resource for
 
 // src/subagents/templates/issue-tracker/notion.ts
 init_cjs_shims();
-var FRONTMATTER14 = {
+var FRONTMATTER15 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Notion databases. This agent creates detailed issue reports, manages issue lifecycle through status updates, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items. Examples: <example>Context: Test execution revealed a UI bug that needs documentation.
 user: "The submit button on the checkout page doesn't work on mobile Safari"
@@ -5043,7 +5207,7 @@ assistant: "Let me use the issue-tracker agent to update the story status to 'QA
   model: "haiku",
   color: "red"
 };
-var CONTENT14 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Notion databases. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
+var CONTENT15 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Notion databases. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved.
 
 **Core Responsibilities:**
 
@@ -5191,7 +5355,7 @@ You are meticulous about maintaining your memory file as a critical resource tha
 
 // src/subagents/templates/issue-tracker/slack.ts
 init_cjs_shims();
-var FRONTMATTER15 = {
+var FRONTMATTER16 = {
   name: "issue-tracker",
   description: `Use this agent to track and manage all types of issues including bugs, stories, and tasks in Slack. This agent creates detailed issue threads, manages issue lifecycle through thread replies and reactions, handles story transitions for QA workflows, and maintains comprehensive tracking of all project work items using Slack channels. Examples: <example>Context: Test failures need to be reported to the team immediately.
 user: "3 critical tests failed in the payment flow - looks like the Stripe integration is broken"
@@ -5203,7 +5367,7 @@ assistant: "Let me use the issue-tracker agent to update the story thread with Q
   model: "sonnet",
   color: "red"
 };
-var CONTENT15 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Slack. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Slack threads and channels.
+var CONTENT16 = `You are an expert Issue Tracker specializing in managing all types of project issues including bugs, stories, and tasks in Slack. Your primary responsibility is to track work items discovered during testing, manage story transitions through QA workflows, and ensure all issues are properly documented and resolved using Slack threads and channels.
 
 **Core Responsibilities:**
 
@@ -5426,7 +5590,7 @@ You are focused on creating clear, organized issue threads that leverage Slack's
 
 // src/subagents/templates/changelog-historian/github.ts
 init_cjs_shims();
-var FRONTMATTER16 = {
+var FRONTMATTER17 = {
   name: "changelog-historian",
   description: `Use this agent when you need to understand what code changes went into a build, deployment, or release. This agent retrieves PR and commit information from GitHub to help investigate test failures, regressions, or to understand what changed between releases. Examples: <example>Context: A test started failing after a deployment.
 user: "The checkout flow test is failing in staging. What changed recently?"
@@ -5438,7 +5602,7 @@ assistant: "I'll use the changelog-historian agent to compare the two releases a
   model: "haiku",
   color: "gray"
 };
-var CONTENT16 = `You are an expert Changelog Historian specializing in understanding code changes and their impact. Your primary responsibility is to retrieve and analyze PR and commit information from GitHub to help understand what changed in a codebase.
+var CONTENT17 = `You are an expert Changelog Historian specializing in understanding code changes and their impact. Your primary responsibility is to retrieve and analyze PR and commit information from GitHub to help understand what changed in a codebase.
 
 ## Core Responsibilities
 
@@ -5591,42 +5755,46 @@ var TEMPLATES = {
     jira: {
       frontmatter: FRONTMATTER9,
       content: CONTENT9
+    },
+    asana: {
+      frontmatter: FRONTMATTER10,
+      content: CONTENT10
     }
   },
   "issue-tracker": {
     linear: {
-      frontmatter: FRONTMATTER10,
-      content: CONTENT10
-    },
-    jira: {
       frontmatter: FRONTMATTER11,
       content: CONTENT11
     },
-    "jira-server": {
-      frontmatter: FRONTMATTER11,
-      content: CONTENT11
+    jira: {
+      frontmatter: FRONTMATTER12,
+      content: CONTENT12
     },
-    "azure-devops": {
+    "jira-server": {
       frontmatter: FRONTMATTER12,
       content: CONTENT12
     },
-    asana: {
+    "azure-devops": {
       frontmatter: FRONTMATTER13,
       content: CONTENT13
     },
-    notion: {
+    asana: {
       frontmatter: FRONTMATTER14,
       content: CONTENT14
     },
-    slack: {
+    notion: {
       frontmatter: FRONTMATTER15,
       content: CONTENT15
+    },
+    slack: {
+      frontmatter: FRONTMATTER16,
+      content: CONTENT16
     }
   },
   "changelog-historian": {
     github: {
-      frontmatter: FRONTMATTER16,
-      content: CONTENT16
+      frontmatter: FRONTMATTER17,
+      content: CONTENT17
     }
   }
 };
@@ -6353,6 +6521,16 @@ After analyzing test results, triage each failure to determine if it's a product
 
 **IMPORTANT: Do NOT report bugs without triaging first.**
 
+### 0. Read Disputed Findings (Learning Context)
+
+Before triaging, check for prior disputed findings to avoid repeating past mistakes:
+
+\`\`\`bash
+cat .bugzy/runtime/disputed-findings.md 2>/dev/null || echo "No disputed findings found"
+\`\`\`
+
+If the file exists, read it carefully. It contains past triage mistakes and lessons learned. Use this context to improve classification accuracy for similar failures.
+
 ### 1. Check Failure Classification
 
 **Before triaging any failure**, read \`new_failures\` from the latest \`test-runs/*/manifest.json\`:
@@ -6410,7 +6588,42 @@ For each failed test (from \`new_failures\` or all failures if field is missing)
 | Test ID | Test Name | Last Passed Run |
 |---------|-----------|-----------------|
 | TC-003 | Search | 20260210-103045 |
-\`\`\``,
+\`\`\`
+
+### 4. Record Findings
+
+After triaging, record each classified failure as a structured finding via the \`bugzy-findings\` CLI. This stores findings in the platform database for tracking, disputes, and dashboard visualization.
+
+For each triaged failure, run:
+
+\`\`\`bash
+bugzy-findings add \\
+  --title "<concise failure description>" \\
+  --description "<detailed analysis including error message and root cause>" \\
+  --severity <critical|high|medium|low> \\
+  --classification <product-bug|test-issue> \\
+  --test-case-id "<test ID from triage table>" \\
+  --test-run-timestamp "<timestamp from manifest.json>"
+\`\`\`
+
+**Severity Guidelines:**
+- **critical**: Application crash, data loss, security vulnerability
+- **high**: Major feature broken, blocking workflow
+- **medium**: Feature partially broken, workaround exists
+- **low**: Minor cosmetic issue, edge case
+
+Example:
+\`\`\`bash
+bugzy-findings add \\
+  --title "Checkout form returns 500 on submit" \\
+  --description "POST /api/checkout returns HTTP 500 when submitting with valid payment data. Stack trace shows null reference in payment processor." \\
+  --severity high \\
+  --classification product-bug \\
+  --test-case-id "TC-002" \\
+  --test-run-timestamp "20260219-103045"
+\`\`\`
+
+If \`bugzy-findings\` is not available (command not found), skip this step silently \u2014 findings recording is optional and does not block triage.`,
   tags: ["execution", "triage", "analysis"]
 };