maestro-flow 0.3.14 → 0.3.16

package/workflows/issue-discover.md

@@ -12,12 +12,9 @@ Automated issue discovery via multi-perspective analysis or prompt-driven explor
 ### Step 1: Parse Mode
 
 ```
-1. Extract mode from $ARGUMENTS:
-   - empty or no arguments → MULTI_PERSPECTIVE mode (Step 3)
-   - "by-prompt" → PROMPT_DRIVEN mode (Step 7)
-
-2. Remaining tokens after mode keyword = DISCOVERY_ARGS
-   For by-prompt: join remaining tokens as USER_PROMPT
+Mode from $ARGUMENTS:
+  empty         → MULTI_PERSPECTIVE (Step 3)
+  "by-prompt"   → PROMPT_DRIVEN (Step 7), remaining tokens = USER_PROMPT
 ```
 
 ---
@@ -25,32 +22,23 @@ Automated issue discovery via multi-perspective analysis or prompt-driven explor
 ### Step 2: Validate Environment
 
 ```
-1. Check .workflow/ exists
-   If not → fatal: "No project initialized. Run /maestro-init first."
-
-2. Check .workflow/issues/ exists
-   If not → mkdir -p .workflow/issues/
-
-3. Ensure issues.jsonl exists
-   If not → touch .workflow/issues/issues.jsonl
-
-4. Generate discovery session ID:
-   DBP-{YYYYMMDD}-{HHmmss}
-
-5. Create discovery session directory:
-   mkdir -p .workflow/issues/discoveries/{SESSION_ID}/
-
-6. Initialize discovery-state.json:
-   {
-     "id": "{SESSION_ID}",
-     "mode": "{discover|discover-by-prompt}",
-     "status": "in_progress",
-     "started_at": "{NOW_ISO}",
-     "completed_at": null,
-     "perspectives_completed": [],
-     "issues_found": 0,
-     "issues_deduplicated": 0
-   }
+Require .workflow/ exists → fatal if missing: "No project initialized. Run /maestro-init first."
+Ensure .workflow/issues/ and issues.jsonl exist (create if missing).
+
+Session ID: DBP-{YYYYMMDD}-{HHmmss}
+Session dir: .workflow/issues/discoveries/{SESSION_ID}/
+
+Initialize discovery-state.json:
+  {
+    "id": "{SESSION_ID}",
+    "mode": "{discover|discover-by-prompt}",
+    "status": "in_progress",
+    "started_at": "{NOW_ISO}",
+    "completed_at": null,
+    "perspectives_completed": [],
+    "issues_found": 0,
+    "issues_deduplicated": 0
+  }
 ```
 
 ---
@@ -108,132 +96,59 @@ Pass to each analysis agent so severity assessments align with project quality s
 ### Step 4: Launch Parallel Analysis
 
 ```
-Launch analysis agents in batches of up to 4 concurrent:
+Batches of 4 concurrent agents:
+  Batch 1: security, performance, reliability, maintainability
+  Batch 2: scalability, ux, accessibility, compliance
 
-Batch 1: security, performance, reliability, maintainability
-Batch 2: scalability, ux, accessibility, compliance
-
-For each perspective, launch a CLI analysis:
+Per perspective → delegate analysis:
 
   maestro delegate "PURPOSE: Discover {PERSPECTIVE} issues in the codebase.
-  Focus: {FOCUS_AREA}
-  Guiding question: {QUESTION}
-
-  TASK:
-  - Scan all source files for {PERSPECTIVE}-related problems
-  - Identify concrete issues with file:line references
-  - Rate each finding: critical / high / medium / low severity
-  - Provide brief fix direction for each finding
-
+  Focus: {FOCUS_AREA} | Question: {QUESTION}
+  TASK: Scan source files → identify issues with file:line → rate severity → suggest fix
   MODE: analysis
   CONTEXT: @**/*
-  EXPECTED: JSON array of findings, each with:
-    title, severity, description, location (file:line), fix_direction, affected_components[]
-  CONSTRAINTS: Only report real issues with evidence, no speculative findings
+  EXPECTED: JSON array: [{ title, severity, description, location, fix_direction, affected_components[] }]
+  CONSTRAINTS: Evidence-backed findings only
   " --to gemini --mode analysis
 
-Store results per perspective in:
-  .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
-
-Update discovery-state.json:
-  perspectives_completed += ["{PERSPECTIVE}"]
+Results → .workflow/issues/discoveries/{SESSION_ID}/{PERSPECTIVE}-findings.json
+Update discovery-state.json: perspectives_completed += ["{PERSPECTIVE}"]
 ```
 
 ### Step 5: Deduplicate Findings
 
 ```
-1. Load all *-findings.json from the session directory
-2. Merge all findings into a single list
-3. Deduplicate by similarity:
-   - Group findings by affected file path
-   - Within each file group, compare descriptions
-   - If two findings describe the same issue (>80% description overlap
-     or same file:line), keep the one with higher severity
-4. Track: issues_found (pre-dedup), issues_deduplicated (post-dedup)
-5. Update discovery-state.json with counts
+Merge all *-findings.json → single list.
+Deduplicate: group by file path, merge entries with >80% description overlap
+or same file:line (keep higher severity).
+Track issues_found (pre-dedup) and issues_deduplicated (post-dedup) in discovery-state.json.
 ```
 
 ### Step 6: Create Issues from Findings
 
 ```
-For each unique finding:
-1. Generate ISS-YYYYMMDD-NNN ID (same logic as create handler in issue.md)
-2. Build issue record:
-   {
-     "id": "{ID}",
-     "title": "{finding.title}",
-     "status": "registered",
-     "priority": {severity_to_priority},
-     "severity": "{finding.severity}",
-     "source": "discovery",
-     "phase_ref": null,
-     "gap_ref": null,
-     "description": "{finding.description}",
-     "fix_direction": "{finding.fix_direction}",
-     "context": {
-       "location": "{finding.location}",
-       "suggested_fix": "",
-       "notes": "Discovered by {PERSPECTIVE} analysis in session {SESSION_ID}"
-     },
-     "tags": ["{PERSPECTIVE}"],
-     "affected_components": {finding.affected_components},
-     "feedback": [],
-     "issue_history": [
-       {
-         "timestamp": "{NOW_ISO}",
-         "from_status": null,
-         "to_status": "registered",
-         "actor": "discovery-agent",
-         "note": "Auto-discovered via {PERSPECTIVE} perspective"
-       }
-     ],
-     "created_at": "{NOW_ISO}",
-     "updated_at": "{NOW_ISO}",
-     "resolved_at": null,
-     "resolution": null
-   }
-
-   Severity-to-priority mapping:
-     critical → 1
-     high     → 2
-     medium   → 3
-     low      → 4
-
-3. Append to .workflow/issues/issues.jsonl
-4. Also append to .workflow/issues/discoveries/{SESSION_ID}/discovery-issues.jsonl
-
-5. Update discovery-state.json:
-   status = "completed"
-   completed_at = NOW_ISO
-
-6. Display summary:
-   ====================================================
-     DISCOVERY COMPLETE: {SESSION_ID}
-     Mode: multi-perspective (8 perspectives)
-     Findings: {issues_found} raw, {issues_deduplicated} unique
-     Issues created: {issues_deduplicated}
-   ====================================================
-
-   BREAKDOWN BY PERSPECTIVE:
-     Security:        {count}
-     Performance:     {count}
-     Reliability:     {count}
-     Maintainability: {count}
-     Scalability:     {count}
-     UX:              {count}
-     Accessibility:   {count}
-     Compliance:      {count}
-
-   BREAKDOWN BY SEVERITY:
-     Critical: {count}
-     High:     {count}
-     Medium:   {count}
-     Low:      {count}
-
-7. Suggest next steps:
-   - Skill({ skill: "manage-issue", args: "list --severity critical" }) -- Review critical issues
-   - Skill({ skill: "manage-issue", args: "list" }) -- View all issues
-   - Skill({ skill: "manage-issue-discover", args: "by-prompt \"...\"" }) -- Explore specific area deeper
+Per unique finding → generate ISS-YYYYMMDD-NNN, build issue record:
+  {
+    "id", "title", "status": "registered",
+    "priority": severity_to_priority(critical→1, high→2, medium→3, low→4),
+    "severity", "source": "discovery",
+    "description", "fix_direction",
+    "context": { "location", "notes": "Discovered by {PERSPECTIVE} in {SESSION_ID}" },
+    "tags": ["{PERSPECTIVE}"],
+    "affected_components",
+    "issue_history": [{ from: null, to: "registered", actor: "discovery-agent" }],
+    "created_at", "updated_at"
+  }
+
+Append to: .workflow/issues/issues.jsonl + discoveries/{SESSION_ID}/discovery-issues.jsonl
+Finalize discovery-state.json: status = "completed", completed_at = NOW_ISO
+
+Display summary: session ID, mode, raw/unique counts, per-perspective breakdown, severity breakdown.
+
+Next steps:
+  - manage-issue list --severity critical
+  - manage-issue list
+  - manage-issue-discover by-prompt "..."
 ```
 
 ---
@@ -243,151 +158,61 @@ For each unique finding:
 ### Step 7: Parse User Prompt
 
 ```
-1. Extract USER_PROMPT from DISCOVERY_ARGS
-   If empty → AskUserQuestion({
-     question: "What kind of issues should I look for?",
-     options: [
-       { label: "Error handling gaps", description: "Missing try/catch, unhandled promises, swallowed errors" },
-       { label: "API contract violations", description: "Mismatched types, missing validation, undocumented endpoints" },
-       { label: "Test coverage gaps", description: "Untested code paths, missing edge cases" },
-       { label: "Custom", description: "Describe what to look for" }
-     ]
-   })
-
-2. Store USER_PROMPT for exploration context
+Extract USER_PROMPT from DISCOVERY_ARGS.
+If empty → prompt user to select focus area:
+  - Error handling gaps | API contract violations | Test coverage gaps | Custom
 ```
 
 ### Step 8: Plan Exploration Dimensions
 
 ```
-Use Gemini CLI to decompose the user prompt into exploration dimensions:
-
-  maestro delegate "PURPOSE: Decompose this issue discovery prompt into 3-5 specific exploration dimensions.
+Delegate to decompose USER_PROMPT into 3-5 exploration dimensions:
 
-  User wants to find: {USER_PROMPT}
-
-  TASK:
-  - Break down the prompt into concrete, searchable dimensions
-  - For each dimension: provide search patterns (regex/keywords), file patterns, and what constitutes a finding
-  - Output as JSON array of dimensions
-
-  MODE: analysis
-  EXPECTED: JSON array:
-    [{
-      name: string,
-      description: string,
-      search_patterns: string[],
-      file_patterns: string[],
-      finding_criteria: string
-    }]
+  maestro delegate "Decompose into searchable dimensions: {USER_PROMPT}
+  EXPECTED: JSON array: [{ name, description, search_patterns[], file_patterns[], finding_criteria }]
   " --to gemini --mode analysis
 
-Store dimensions in:
-  .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
+Store → .workflow/issues/discoveries/{SESSION_ID}/exploration-plan.json
 ```
 
 ### Step 9: Gather Codebase Context
 
 ```
-For each exploration dimension:
-
-1. Use @~/.maestro/templates/search-tool.json for semantic search:
-   {search_tool}(
-     project_root_path="{PROJECT_ROOT}",
-     query="{dimension.description}"
-   )
-
-2. Use ripgrep for pattern-based search:
-   For each pattern in dimension.search_patterns:
-     rg "{pattern}" --type-add "src:*.{ts,tsx,js,jsx,py,java,go}" --type src -n
-
-3. Collect matching files and code snippets
-4. Store context per dimension in:
-   .workflow/issues/discoveries/{SESSION_ID}/{dimension.name}-context.md
+Per dimension:
+  1. Semantic search via {search_tool}(query="{dimension.description}")
+  2. Pattern search via rg for each dimension.search_patterns
+  3. Collect matching files/snippets → {SESSION_ID}/{dimension.name}-context.md
 ```
 
 ### Step 10: Iterative Exploration Loop
 
 ```
-Max 3 rounds of exploration:
-
-Round 1: Initial analysis
-  - Analyze gathered context from Step 9
-  - Identify concrete issues with evidence
-  - Identify gaps in coverage (areas not yet explored)
-
-Round 2: Deepen search (if gaps found)
-  - For each identified gap:
-    - Refine search patterns
-    - Search adjacent files/modules
-    - Cross-reference with related code
-  - Merge new findings with Round 1
-
-Round 3: Final sweep (if significant gaps remain)
-  - Focus on high-severity patterns not yet covered
-  - Check cross-module interactions
-  - Finalize findings list
-
-After each round:
-  - Log findings count and coverage assessment
-  - If no new gaps or no new findings → exit loop early
-
-Store exploration log:
-  .workflow/issues/discoveries/{SESSION_ID}/exploration-log.md
-
-  ## Round {N}
-  - Files analyzed: {count}
-  - Findings: {count} new, {total} cumulative
-  - Gaps remaining: {list or "none"}
+Up to 3 rounds (exit early if no new gaps/findings):
+  Round 1: Analyze context → identify issues + coverage gaps
+  Round 2: Refine patterns for gaps → search adjacent files → merge findings
+  Round 3: Final sweep on uncovered high-severity patterns + cross-module interactions
+
+Log per round → {SESSION_ID}/exploration-log.md:
+  Files analyzed, new/cumulative findings, remaining gaps.
 ```
 
 ### Step 11: Generate Issues from Findings
 
 ```
-1. Collect all findings from exploration rounds
-2. Deduplicate (same logic as Step 5):
-   - Group by affected file
-   - Merge similar descriptions
-   - Keep higher-severity duplicate
-
-3. For each unique finding:
-   - Generate ISS-YYYYMMDD-NNN ID
-   - Build issue record (same structure as Step 6)
-   - Set source = "discovery"
-   - Set tags = ["prompt-discovery", "{relevant dimension name}"]
-   - Set context.notes = "Discovered via prompt: {USER_PROMPT}"
-
-4. Append to .workflow/issues/issues.jsonl
-5. Append to .workflow/issues/discoveries/{SESSION_ID}/discovery-issues.jsonl
-
-6. Update discovery-state.json:
-   status = "completed"
-   completed_at = NOW_ISO
-
-7. Display summary:
-   ====================================================
-     DISCOVERY COMPLETE: {SESSION_ID}
-     Mode: prompt-driven
-     Prompt: "{USER_PROMPT}"
-     Rounds: {rounds_executed}
-     Findings: {raw_count} raw, {deduped_count} unique
-     Issues created: {deduped_count}
-   ====================================================
-
-   FINDINGS BY DIMENSION:
-     {dimension.name}: {count}
-     ...
-
-   BREAKDOWN BY SEVERITY:
-     Critical: {count}
-     High:     {count}
-     Medium:   {count}
-     Low:      {count}
-
-8. Suggest next steps:
-   - Skill({ skill: "manage-issue", args: "list --source discovery" }) -- View discovered issues
-   - Skill({ skill: "manage-issue-discover" }) -- Run full 8-perspective scan
-   - Skill({ skill: "manage-issue-discover", args: "by-prompt \"...\"" }) -- Explore another area
+Deduplicate all findings (same logic as Step 5).
+Per unique finding → issue record (same structure as Step 6):
+  source = "discovery", tags = ["prompt-discovery", "{dimension.name}"]
+  context.notes = "Discovered via prompt: {USER_PROMPT}"
+
+Append to: issues.jsonl + discoveries/{SESSION_ID}/discovery-issues.jsonl
+Finalize discovery-state.json: status = "completed"
+
+Display summary: session, prompt, rounds, raw/unique counts, per-dimension + severity breakdown.
+
+Next steps:
+  - manage-issue list --source discovery
+  - manage-issue-discover (full 8-perspective scan)
+  - manage-issue-discover by-prompt "..." (explore another area)
 ```
 
 ---