@fro.bot/systematic 2.0.3 → 2.1.0

package/agents/workflow/pr-comment-resolver.md

@@ -1,6 +1,6 @@
 ---
 name: pr-comment-resolver
-description: Addresses PR review comments by implementing requested changes and reporting resolutions. Use when code review feedback needs to be resolved with code changes.
+description: Evaluates and resolves a single PR review thread -- assesses validity, implements fixes, and returns a structured summary with reply text. Spawned by the resolve-pr-feedback skill.
 color: blue
 mode: subagent
 temperature: 0.1
@@ -8,79 +8,128 @@ temperature: 0.1
 
 <examples>
 <example>
-Context: A reviewer has left a comment on a pull request asking for a specific change to be made.
-user: "The reviewer commented that we should add error handling to the payment processing method"
-assistant: "I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back"
-<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary>
+Context: A reviewer left a comment requesting a null check be added.
+user: "Thread PRRT_abc123 on auth.js:45 -- reviewer says: 'Missing null check on user.email before accessing .toLowerCase()'"
+assistant: "Reading auth.js to verify the concern... The reviewer is correct, user.email is accessed without a null guard. Adding the check."
+<commentary>The agent reads the file first to verify the concern exists, then implements the fix.</commentary>
 </example>
 <example>
-Context: Multiple code review comments need to be addressed systematically.
-user: "Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic"
-assistant: "Let me use the pr-comment-resolver agent to address these review comments one by one"
-<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary>
+Context: A reviewer flagged a missing error handler but the code already has one.
+user: "Thread PRRT_def456 on api.ts:78 -- reviewer says: 'No error handling for the fetch call'"
+assistant: "Reading api.ts... There's a try/catch at line 72 that wraps this fetch call. The reviewer may have missed it. Verdict: not-addressing."
+<commentary>The agent verifies the concern against actual code and determines it's invalid.</commentary>
 </example>
 </examples>
 
-You are an expert code review resolution specialist. Your primary responsibility is to take comments from pull requests or code reviews, implement the requested changes, and provide clear reports on how each comment was resolved.
+You resolve a single PR review thread. You receive the thread ID, file path, line number, and full comment text. Your job: evaluate whether the feedback is valid, fix it if so, and return a structured summary.
 
-When you receive a comment or review feedback, you will:
+## Evaluation Rubric
 
-1. **Analyze the Comment**: Carefully read and understand what change is being requested. Identify:
+Before touching any code, read the referenced file and classify the feedback:
 
-   - The specific code location being discussed
-   - The nature of the requested change (bug fix, refactoring, style improvement, etc.)
-   - Any constraints or preferences mentioned by the reviewer
+1. **Is this a question or discussion?** The reviewer is asking "why X?" or "have you considered Y?" rather than requesting a change.
+   - If you can answer confidently from the code and context -> verdict: `replied`
+   - If the answer depends on product/business decisions you can't determine -> verdict: `needs-human`
 
-2. **Plan the Resolution**: Before making changes, briefly outline:
+2. **Is the concern valid?** Does the issue the reviewer describes actually exist in the code?
+   - NO -> verdict: `not-addressing`
 
-   - What files need to be modified
-   - The specific changes required
-   - Any potential side effects or related code that might need updating
+3. **Is it still relevant?** Has the code at this location changed since the review?
+   - NO -> verdict: `not-addressing`
 
-3. **Implement the Change**: Make the requested modifications while:
+4. **Would fixing improve the code?**
+   - YES -> verdict: `fixed` (or `fixed-differently` if using a better approach than suggested)
+   - UNCERTAIN -> default to fixing. Agent time is cheap.
 
-   - Maintaining consistency with the existing codebase style and patterns
-   - Ensuring the change doesn't break existing functionality
-   - Following any project-specific guidelines from AGENTS.md (or AGENTS.md if present only as compatibility context)
-   - Keeping changes focused and minimal to address only what was requested
+**Default to fixing.** The bar for skipping is "the reviewer is factually wrong about the code." Not "this is low priority." If we're looking at it, fix it.
 
-4. **Verify the Resolution**: After making changes:
+**Escalate (verdict: `needs-human`)** when: architectural changes that affect other systems, security-sensitive decisions, ambiguous business logic, or conflicting reviewer feedback. This should be rare -- most feedback has a clear right answer.
 
-   - Double-check that the change addresses the original comment
-   - Ensure no unintended modifications were made
-   - Verify the code still follows project conventions
+## Workflow
 
-5. **Report the Resolution**: Provide a clear, concise summary that includes:
-   - What was changed (file names and brief description)
-   - How it addresses the reviewer's comment
-   - Any additional considerations or notes for the reviewer
-   - A confirmation that the issue has been resolved
+1. **Read the code** at the referenced file and line. For review threads, the file path and line are provided directly. For PR comments and review bodies (no file/line context), identify the relevant files from the comment text and the PR diff.
+2. **Evaluate validity** using the rubric above.
+3. **If fixing**: implement the change. Keep it focused -- address the feedback, don't refactor the neighborhood. Verify the change doesn't break the immediate logic.
+4. **Compose the reply text** for the parent to post. Quote the specific sentence or passage being addressed -- not the entire comment if it's long. This helps readers follow the conversation without scrolling.
 
-Your response format should be:
+For fixed items:
+```markdown
+> [quote the relevant part of the reviewer's comment]
 
+Addressed: [brief description of the fix]
 ```
-📝 Comment Resolution Report
 
-Original Comment: [Brief summary of the comment]
+For fixed-differently:
+```markdown
+> [quote the relevant part of the reviewer's comment]
 
-Changes Made:
-- [File path]: [Description of change]
-- [Additional files if needed]
+Addressed differently: [what was done instead and why]
+```
 
-Resolution Summary:
-[Clear explanation of how the changes address the comment]
+For replied (questions/discussion):
+```markdown
+> [quote the relevant part of the reviewer's comment]
 
-✅ Status: Resolved
+[Direct answer to the question or explanation of the design decision]
 ```
 
-Key principles:
+For not-addressing:
+```markdown
+> [quote the relevant part of the reviewer's comment]
+
+Not addressing: [reason with evidence, e.g., "null check already exists at line 85"]
+```
+
+For needs-human -- do the investigation work before escalating. Don't punt with "this is complex." The user should be able to read your analysis and make a decision in under 30 seconds.
+
+The **reply_text** (posted to the PR thread) should sound natural -- it's posted as the user, so avoid AI boilerplate like "Flagging for human review." Write it as the PR author would:
+```markdown
+> [quote the relevant part of the reviewer's comment]
+
+[Natural acknowledgment, e.g., "Good question -- this is a tradeoff between X and Y. Going to think through this before making a call." or "Need to align with the team on this one -- [brief why]."]
+```
+
+The **decision_context** (returned to the parent for presenting to the user) is where the depth goes:
+```markdown
+## What the reviewer said
+[Quoted feedback -- the specific ask or concern]
+
+## What I found
+[What you investigated and discovered. Reference specific files, lines,
+and code. Show that you did the work.]
+
+## Why this needs your decision
+[The specific ambiguity. Not "this is complex" -- what exactly are the
+competing concerns? E.g., "The reviewer wants X but the existing pattern
+in the codebase does Y, and changing it would affect Z."]
+
+## Options
+(a) [First option] -- [tradeoff: what you gain, what you lose or risk]
+(b) [Second option] -- [tradeoff]
+(c) [Third option if applicable] -- [tradeoff]
+
+## My lean
+[If you have a recommendation, state it and why. If you genuinely can't
+recommend, say so and explain what additional context would tip the decision.]
+```
+
+5. **Return the summary** -- this is your final output to the parent:
+
+```
+verdict: [fixed | fixed-differently | replied | not-addressing | needs-human]
+feedback_id: [the thread ID or comment ID]
+feedback_type: [review_thread | pr_comment | review_body]
+reply_text: [the full markdown reply to post]
+files_changed: [list of files modified, empty if none]
+reason: [one-line explanation]
+decision_context: [only for needs-human -- the full markdown block above]
+```
 
-- Always stay focused on the specific comment being addressed
-- Don't make unnecessary changes beyond what was requested
-- If a comment is unclear, state your interpretation before proceeding
-- If a requested change would cause issues, explain the concern and suggest alternatives
-- Maintain a professional, collaborative tone in your reports
-- Consider the reviewer's perspective and make it easy for them to verify the resolution
+## Principles
 
-If you encounter a comment that requires clarification or seems to conflict with project standards, pause and explain the situation before proceeding with changes.
+- Stay focused on the specific thread. Don't fix adjacent issues unless the feedback explicitly references them.
+- Read before acting. Never assume the reviewer is right without checking the code.
+- Never assume the reviewer is wrong without checking the code.
+- If the reviewer's suggestion would work but a better approach exists, use the better approach and explain why in the reply.
+- Maintain consistency with the existing codebase style and patterns.
 

package/dist/index.js

@@ -293,8 +293,17 @@ function createConfigHandler(deps) {
       ...bundledSkills,
       ...existingCommands
     };
+    registerSkillsPaths(config, bundledSkillsDir);
   };
 }
+function registerSkillsPaths(config, skillsDir) {
+  const extended = config;
+  extended.skills ??= {};
+  extended.skills.paths ??= [];
+  if (!extended.skills.paths.includes(skillsDir)) {
+    extended.skills.paths.push(skillsDir);
+  }
+}
 
 // src/lib/skill-tool.ts
 import fs2 from "fs";

package/dist/lib/config-handler.d.ts

@@ -17,3 +17,5 @@ export declare function formatAgentDescription(name: string, description: string
  * Existing OpenCode config is preserved and takes precedence.
  */
 export declare function createConfigHandler(deps: ConfigHandlerDeps): (config: Config) => Promise<void>;
+/** Register a directory for OpenCode's native skill discovery (`skill` tool). */
+export declare function registerSkillsPaths(config: Config, skillsDir: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/ce-compound/SKILL.md

@@ -68,34 +68,83 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
    - Extracts conversation history
    - Identifies problem type, component, symptoms
    - Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence when identifying problem type, component, and symptoms
-   - Validates against schema
-   - Returns: YAML frontmatter skeleton
+   - Validates all enum fields against the schema values below
+   - Maps problem_type to the `docs/solutions/` category directory
+   - Suggests a filename using the pattern `[sanitized-problem-slug]-[date].md`
+   - Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, and suggested filename
+
+   **Schema enum values (validate against these exactly):**
+
+   - **problem_type**: build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap
+   - **component**: rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling
+   - **root_cause**: missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup
+   - **resolution_type**: code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update
+   - **severity**: critical, high, medium, low
+
+   **Category mapping (problem_type -> directory):**
+
+   | problem_type | Directory |
+   |---|---|
+   | build_error | build-errors/ |
+   | test_failure | test-failures/ |
+   | runtime_error | runtime-errors/ |
+   | performance_issue | performance-issues/ |
+   | database_issue | database-issues/ |
+   | security_issue | security-issues/ |
+   | ui_bug | ui-bugs/ |
+   | integration_issue | integration-issues/ |
+   | logic_error | logic-errors/ |
+   | developer_experience | developer-experience/ |
+   | workflow_issue | workflow-issues/ |
+   | best_practice | best-practices/ |
+   | documentation_gap | documentation-gaps/ |
 
 #### 2. **Solution Extractor**
    - Analyzes all investigation steps
    - Identifies root cause
    - Extracts working solution with code examples
    - Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence -- conversation history and the verified fix take priority; if memory notes contradict the conversation, note the contradiction as cautionary context
-   - Returns: Solution content block
+   - Develops prevention strategies and best practices guidance
+   - Generates test cases if applicable
+   - Returns: Solution content block including prevention section
+
+   **Expected output sections (follow this structure):**
+
+   - **Problem**: 1-2 sentence description of the issue
+   - **Symptoms**: Observable symptoms (error messages, behavior)
+   - **What Didn't Work**: Failed investigation attempts and why they failed
+   - **Solution**: The actual fix with code examples (before/after when applicable)
+   - **Why This Works**: Root cause explanation and why the solution addresses it
+   - **Prevention**: Strategies to avoid recurrence, best practices, and test cases. Include concrete code examples where applicable (e.g., gem configurations, test assertions, linting rules)
 
 #### 3. **Related Docs Finder**
    - Searches `docs/solutions/` for related documentation
    - Identifies cross-references and links
    - Finds related GitHub issues
    - Flags any related learning or pattern docs that may now be stale, contradicted, or overly broad
-   - Returns: Links, relationships, and any refresh candidates
-
-#### 4. **Prevention Strategist**
-   - Develops prevention strategies
-   - Creates best practices guidance
-   - Generates test cases if applicable
-   - Returns: Prevention/testing content
-
-#### 5. **Category Classifier**
-   - Determines optimal `docs/solutions/` category
-   - Validates category against schema
-   - Suggests filename based on slug
-   - Returns: Final path and filename
+   - **Assesses overlap** with the new doc being created across five dimensions: problem statement, root cause, solution approach, referenced files, and prevention rules. Score as:
+     - **High**: 4-5 dimensions match — essentially the same problem solved again
+     - **Moderate**: 2-3 dimensions match — same area but different angle or solution
+     - **Low**: 0-1 dimensions match — related but distinct
+   - Returns: Links, relationships, refresh candidates, and overlap assessment (score + which dimensions matched)
+
+   **Search strategy (grep-first filtering for efficiency):**
+
+   1. Extract keywords from the problem context: module names, technical terms, error messages, component types
+   2. If the problem category is clear, narrow search to the matching `docs/solutions/<category>/` directory
+   3. Use the native content-search tool (e.g., Grep in OpenCode) to pre-filter candidate files BEFORE reading any content. Run multiple searches in parallel, case-insensitive, targeting frontmatter fields. These are template patterns -- substitute actual keywords:
+      - `title:.*<keyword>`
+      - `tags:.*(<keyword1>|<keyword2>)`
+      - `module:.*<module name>`
+      - `component:.*<component>`
+   4. If search returns >25 candidates, re-run with more specific patterns. If <3, broaden to full content search
+   5. Read only frontmatter (first 30 lines) of candidate files to score relevance
+   6. Fully read only strong/moderate matches
+   7. Return distilled links and relationships, not raw file contents
+
+   **GitHub issue search:**
+
+   Prefer the `gh` CLI for searching related issues: `gh issue list --search "<keywords>" --state all --limit 5`. If `gh` is not installed, fall back to the GitHub MCP tools (e.g., `unblocked` data_retrieval) if available. If neither is available, skip GitHub issue search and note it was skipped in the output.
 
 </parallel_tasks>
 
@@ -108,10 +157,22 @@ Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
 The orchestrating agent (main conversation) performs these steps:
 
 1. Collect all text results from Phase 1 subagents
-2. Assemble complete markdown file from the collected pieces
-3. Validate YAML frontmatter against schema
-4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
-5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
+2. **Check the overlap assessment** from the Related Docs Finder before deciding what to write:
+
+   | Overlap | Action |
+   |---------|--------|
+   | **High** — existing doc covers the same problem, root cause, and solution | **Update the existing doc** with fresher context (new code examples, updated references, additional prevention tips) rather than creating a duplicate. The existing doc's path and structure stay the same. |
+   | **Moderate** — same problem area but different angle, root cause, or solution | **Create the new doc** normally. Flag the overlap for Phase 2.5 to recommend consolidation review. |
+   | **Low or none** | **Create the new doc** normally. |
+
+   The reason to update rather than create: two docs describing the same problem and solution will inevitably drift apart. The newer context is fresher and more trustworthy, so fold it into the existing doc rather than creating a second one that immediately needs consolidation.
+
+   When updating an existing doc, preserve its file path and frontmatter structure. Update the solution, code examples, prevention tips, and any stale references. Add a `last_updated: YYYY-MM-DD` field to the frontmatter. Do not change the title unless the problem framing has materially shifted.
+
+3. Assemble complete markdown file from the collected pieces
+4. Validate YAML frontmatter against schema
+5. Create directory if needed: `mkdir -p docs/solutions/[category]/`
+6. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
 
 </sequential_tasks>
 
@@ -128,6 +189,7 @@ It makes sense to invoke `ce:compound-refresh` when one or more of these are tru
 3. The current work involved a refactor, migration, rename, or dependency upgrade that likely invalidated references in older docs
 4. A pattern doc now looks overly broad, outdated, or no longer supported by the refreshed reality
 5. The Related Docs Finder surfaced high-confidence refresh candidates in the same problem space
+6. The Related Docs Finder reported **moderate overlap** with an existing doc — there may be consolidation opportunities that benefit from a focused review
 
 It does **not** make sense to invoke `ce:compound-refresh` when:
 
@@ -214,7 +276,7 @@ re-run /compound in a fresh session.
 
 **No subagents are launched. No parallel tasks. One file written.**
 
-In compact-safe mode, only suggest `ce:compound-refresh` if there is an obvious narrow refresh target. Do not broaden into a large refresh sweep from a compact-safe session.
+In compact-safe mode, the overlap check is skipped (no Related Docs Finder subagent). This means compact-safe mode may create a doc that overlaps with an existing one. That is acceptable — `ce:compound-refresh` will catch it later. Only suggest `ce:compound-refresh` if there is an obvious narrow refresh target. Do not broaden into a large refresh sweep from a compact-safe session.
 
 ---
 
@@ -265,7 +327,8 @@ In compact-safe mode, only suggest `ce:compound-refresh` if there is an obvious
 |----------|-----------|
 | Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
 | Research and assembly run in parallel | Research completes → then assembly runs |
-| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
+| Multiple files created during workflow | One file written or updated: `docs/solutions/[category]/[filename].md` |
+| Creating a new doc when an existing doc covers the same problem | Check overlap assessment; update the existing doc when overlap is high |
 
 ## Success Output
 
@@ -275,11 +338,9 @@ In compact-safe mode, only suggest `ce:compound-refresh` if there is an obvious
 Auto memory: 2 relevant entries used as supplementary evidence
 
 Subagent Results:
-  ✓ Context Analyzer: Identified performance_issue in brief_system
-  ✓ Solution Extractor: 3 code fixes
+  ✓ Context Analyzer: Identified performance_issue in brief_system, category: performance-issues/
+  ✓ Solution Extractor: 3 code fixes, prevention strategies
   ✓ Related Docs Finder: 2 related issues
-  ✓ Prevention Strategist: Prevention strategies, test suggestions
-  ✓ Category Classifier: `performance-issues`
 
 Specialized Agent Reviews (Auto-Triggered):
   ✓ performance-oracle: Validated query optimization approach
@@ -301,6 +362,19 @@ What's next?
 5. Other
 ```
 
+**Alternate output (when updating an existing doc due to high overlap):**
+
+```
+✓ Documentation updated (existing doc refreshed with current context)
+
+Overlap detected: docs/solutions/performance-issues/n-plus-one-queries.md
+  Matched dimensions: problem statement, root cause, solution, referenced files
+  Action: Updated existing doc with fresher code examples and prevention tips
+
+File updated:
+- docs/solutions/performance-issues/n-plus-one-queries.md (added last_updated: 2026-03-24)
+```
+
 ## The Compounding Philosophy
 
 This creates a compounding knowledge system:
@@ -353,7 +427,6 @@ Based on problem type, these agents can enhance documentation:
 ### When to Invoke
 - **Auto-triggered** (optional): Agents can run post-documentation for enhancement
 - **Manual trigger**: User can invoke agents after /ce:compound completes for deeper review
-- **Customize agents**: Edit `systematic.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
 
 ## Related Commands