From e8667520d375e7c753e9c4b9365ae7abe2411c15 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Sat, 2 May 2026 14:07:15 +0300 Subject: [PATCH 1/6] Reduce the size and remove duplicate content on oversized SKILL.MD files --- bugfix/SKILL.md | 110 +++------------------------------------- bugfix/guidelines.md | 16 ++++++ cve-fix/SKILL.md | 41 ++------------- cve-fix/guidelines.md | 11 ++++ docs-writer/SKILL.md | 84 ++++-------------------------- kcs/SKILL.md | 84 +++--------------------------- skill-reviewer/SKILL.md | 52 ++----------------- triage/SKILL.md | 63 ++--------------------- triage/guidelines.md | 16 ++++++ 9 files changed, 75 insertions(+), 402 deletions(-) diff --git a/bugfix/SKILL.md b/bugfix/SKILL.md index 91e47d3..cf5c12d 100644 --- a/bugfix/SKILL.md +++ b/bugfix/SKILL.md @@ -12,112 +12,14 @@ description: >- ## Quick Start -1. If the user invoked a specific command (e.g. `/unattended`, `/diagnose`, `/fix`), read the matching file in `commands/{command}.md` and follow it. -2. Otherwise, read `skills/controller.md` to load the workflow controller: +1. If the user invoked a specific command (e.g. `/unattended`, `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. +2. If the user invoked `/unattended`, read `skills/unattended.md` — this runs diagnose → fix → test → review to completion without human input. +3. Otherwise, read `skills/controller.md` to load the workflow controller: - If the user provided a bug report or issue URL, execute the `/assess` phase - Otherwise, execute `/start` to present available phases -Each phase skill (e.g. `skills/diagnose.md`) follows this pattern: - -1. Announce the phase: *"Starting /diagnose."* -2. Execute the skill's steps — search code, run commands, collect evidence -3. Write findings to the artifact directory and return to the controller - -```bash -# Artifact directory setup and example commands during investigation -mkdir -p .artifacts/bugfix/421 -rg "NullPointerException" --type java -l -git log --oneline -10 -- src/auth/AuthService.java -git blame src/auth/AuthService.java | head -100 -``` - -## Example: Running /diagnose - -To execute the diagnose phase: - -1. Create the artifact dir: `mkdir -p .artifacts/bugfix/421` -2. Find the failure location: `rg "NullPointerException" --type java -l` -3. Trace when it was introduced: `git blame ` and `git log --oneline -10 -- ` -4. Write `.artifacts/bugfix/421/root-cause.md` using this structure: - -```markdown -# Root Cause — Issue #421 - -## Root Cause Summary -`AuthService.java:87` calls `session.getUserId()` before null-check. - -## Evidence -- Stack trace: `AuthService.authenticate():87` -- `git blame` shows null-check removed in commit `a1b2c3d` - -## Affected Components -- `AuthService.java:87` — missing null guard - -## Impact Assessment -- Severity: High -- Blast radius: All unauthenticated login attempts - -## Recommended Fix -Add null-check before `getUserId()` call. - -## Confidence: High (95%) -``` - -See `skills/diagnose.md` for the full process and additional fields. - -## Example Session - -```text -User: "Fix issue #421 — NullPointerException on login" - -/assess → reads bug report, proposes plan (inline; no artifact) -/reproduce → confirms the failure with a test - → writes .artifacts/bugfix/421/reproduction.md -/diagnose → traces root cause to AuthService.java:87 - → writes .artifacts/bugfix/421/root-cause.md -/fix → adds null-check, minimal diff -/test → regression test passes ✓ - → if tests fail → return to /fix -/pr → pushes branch, creates draft PR -``` - -## Phases - -Systematic bug resolution through these phases: - -0. **Start** (`/start`) — Present available phases and help choose where to begin -1. **Assess** (`/assess`) — Read the bug report, explain understanding, propose a plan -2. **Reproduce** (`/reproduce`) — Confirm and document the bug -3. **Diagnose** (`/diagnose`) — Identify root cause and impact -4. **Fix** (`/fix`) — Implement the solution -5. **Test** (`/test`) — Verify the fix, create regression tests -6. **Review** (`/review`) — *(Optional)* Critically evaluate fix and tests -7. **Document** (`/document`) — Release notes and documentation -8. **PR** (`/pr`) — Submit a pull request -9. **Feedback** (`/feedback`) — Address PR review comments - -## Phase Transitions - -Each phase must meet its exit criteria before the next phase begins. If a later phase reveals problems, loop back: - -- `/assess` → proceed when the bug report is understood and a plan is proposed -- `/reproduce` → proceed when the bug is reliably triggered with documented steps -- `/diagnose` → proceed when a root cause is confirmed with supporting evidence (stack trace, git blame, code path) -- `/fix` → proceed when the implementation addresses the confirmed root cause -- `/test` → proceed when all new and existing tests pass; if tests fail, return to `/fix` -- `/review` → if the fix is inadequate or edge cases are missed, return to `/diagnose` or `/fix` - -## Unattended Mode - -For unattended execution (CI/CD bots, automated systems), use -`skills/unattended.md` instead of the interactive controller. It chains -diagnose → fix → test → review with self-correction loops and runs to -completion without human input. See `/unattended` or read the skill directly. - -## File Layout - -The workflow controller lives at `skills/controller.md` (interactive) or -`skills/unattended.md` (unattended). -Phase skills are at `skills/{name}.md`. +If a step fails or produces unexpected output, stop and report the error to the +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/bugfix/guidelines.md b/bugfix/guidelines.md index ea92655..1ffe327 100644 --- a/bugfix/guidelines.md +++ b/bugfix/guidelines.md @@ -64,6 +64,22 @@ Note: retry-limit exhaustion in unattended mode degrades gracefully rather than triggering escalation — see `skills/unattended.md` for details. +## Example Session + +```text +User: "Fix issue #421 — NullPointerException on login" + +/assess → reads bug report, proposes plan (inline; no artifact) +/reproduce → confirms the failure with a test + → writes .artifacts/bugfix/421/reproduction.md +/diagnose → traces root cause to AuthService.java:87 + → writes .artifacts/bugfix/421/root-cause.md +/fix → adds null-check, minimal diff +/test → regression test passes ✓ + → if tests fail → return to /fix +/pr → pushes branch, creates draft PR +``` + ## Working With the Project This workflow gets deployed into different projects. Respect the target project: diff --git a/cve-fix/SKILL.md b/cve-fix/SKILL.md index 06cc7bc..569e25b 100644 --- a/cve-fix/SKILL.md +++ b/cve-fix/SKILL.md @@ -16,43 +16,8 @@ description: >- 1. If the user invoked a specific command (e.g. `/patch`, `/pr`), read `commands/{command}.md` and follow it. 2. Otherwise, read `skills/controller.md` to load the workflow controller and begin with `/start`. -### Executing a Phase +If a step fails or produces unexpected output, stop and report the error to the +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. -To run any phase, follow these steps exactly: - -1. Announce the phase: *"Starting /{phase}."* -2. Read the phase skill file: `skills/{phase}.md` -3. Execute each step in the skill — the user should see your progress -4. If a step fails or produces unexpected output, stop and report the error to the user. - Do not advance to the next phase. Offer to retry the failed step or escalate. -5. Write outputs to the artifact directory: - ```bash - mkdir -p .artifacts/cve-fix/{context} - ``` -6. Report results, then re-read `skills/controller.md` to determine next steps -7. Present options and **wait for the user** before advancing - -### Phase Quick Reference - -| Phase | Key Action | Artifact | -|-------|-----------|----------| -| `/start` | Fetch Jira ticket or accept CVE ID, detect ecosystem | `context.md` | -| `/patch` | Try fixes in order: direct update → transitive → override → major | `patch-log.md`, `pr-description.md` | -| `/validate` | `go list -m`/`npm ls`/etc. to confirm version, run project tests | `validation-results.md` | -| `/pr` | `git checkout -b cve-fix/{ctx}`, commit, `gh pr create --draft --base {branch}` | PR URL | -| `/backport` | `git cherry-pick -x [-m 1] {sha}` per release branch, create backport PRs | `backport-log.md` | -| `/close` | Verify PRs merged, transition Jira tickets to MODIFIED or ON_QA | `close-report.md` | - -### Example - -User: *"Fix vulnerability EDM-1234"* - -1. `/start` — fetch Jira ticket EDM-1234, extract CVE-2025-53547 (HIGH) in `helm.sh/helm/v3`, detect Go ecosystem → writes `.artifacts/cve-fix/EDM-1234/context.md` -2. `/patch` — `go get helm.sh/helm/v3@v3.15.0`, then `go mod tidy` → writes `patch-log.md`, `pr-description.md` -3. `/validate` — `go list -m helm.sh/helm/v3` confirms v3.15.0, run tests → writes `validation-results.md` -4. `/pr` — `git checkout -b cve-fix/EDM-1234`, then `gh pr create --draft --base main` → draft PR -5. `/backport` — cherry-pick to `release-2.16`, create backport PR → writes `backport-log.md` -6. `/close` — verify PRs merged, update Jira tickets to ON_QA → writes `close-report.md` - -For phases, transitions, patch strategies, and file layout details, see `README.md`. For principles, hard limits, safety, and escalation rules, see `guidelines.md`. diff --git a/cve-fix/guidelines.md b/cve-fix/guidelines.md index d10b43d..181da43 100644 --- a/cve-fix/guidelines.md +++ b/cve-fix/guidelines.md @@ -89,3 +89,14 @@ Stop and ask the user when: - Adopt the project's coding style and conventions - Respect the project's branching strategy and PR process - Don't assume tools are missing — check for version managers (e.g. `nvm`, `pyenv`, `asdf`) before concluding a runtime isn't available + +## Example + +User: *"Fix vulnerability EDM-1234"* + +1. `/start` — fetch Jira ticket EDM-1234, extract CVE-2025-53547 (HIGH) in `helm.sh/helm/v3`, detect Go ecosystem → writes `.artifacts/cve-fix/EDM-1234/context.md` +2. `/patch` — `go get helm.sh/helm/v3@v3.15.0`, then `go mod tidy` → writes `patch-log.md`, `pr-description.md` +3. `/validate` — `go list -m helm.sh/helm/v3` confirms v3.15.0, run tests → writes `validation-results.md` +4. `/pr` — `git checkout -b cve-fix/EDM-1234`, then `gh pr create --draft --base main` → draft PR +5. `/backport` — cherry-pick to `release-2.16`, create backport PR → writes `backport-log.md` +6. `/close` — verify PRs merged, update Jira tickets to ON_QA → writes `close-report.md` diff --git a/docs-writer/SKILL.md b/docs-writer/SKILL.md index ef0710e..c4ab1b2 100644 --- a/docs-writer/SKILL.md +++ b/docs-writer/SKILL.md @@ -6,80 +6,14 @@ description: Documentation workflow that converts requirements into structured A ## Quick Start -1. Read `skills/controller.md` to load the workflow controller -2. If a `ticket_id` is known, check `.artifacts/${ticket_id}/` for existing artifacts and resume from the next incomplete phase (see "Resuming Work" in the controller) -3. If no artifacts exist and the user provided a Jira ticket, GitHub issue URL, or feature description, execute the `/gather` phase -4. Otherwise, execute the first phase the user requests (e.g. `/plan` if they already have context) - -Each phase skill (e.g. `skills/gather-context.md`) follows this pattern: - -1. Announce the phase: *"Starting /gather."* -2. Execute the skill's steps — fetch requirements, synthesize context, write artifact -3. Write output to the artifact directory and return to the controller - -```bash -# Artifact directory and example validation -mkdir -p .artifacts/JIRA-123 -vale .artifacts/JIRA-123/03-final-docs.adoc -``` - -## Example: Running /gather - -To execute the gather phase without opening external files: - -1. `mkdir -p .artifacts/JIRA-123` -2. Fetch the ticket (Jira MCP) or issue (`gh issue view --repo `); capture description, acceptance criteria, comments -3. Find linked PRs (e.g. titles with `[JIRA-123]`), fetch diffs with `gh pr diff --repo ` -4. Synthesize Why, What, and technical changes; write `.artifacts/JIRA-123/01-context.md` - -## Example: Running /validate - -Fully executable without opening other files: - -1. Parse `.artifacts/${ticket_id}/03-final-docs.adoc` for `// File: path/to/file.adoc` lines to get target paths -2. From repo root: `vale .artifacts/${ticket_id}/03-final-docs.adoc` (or run Vale on each path if you wrote temp `.adoc` files under `.artifacts/${ticket_id}/`) -3. If Vale reports errors: edit the draft to fix style/terminology, overwrite `03-final-docs.adoc`, run `vale` again; repeat until clean -4. Optional: from the guide directory run `./template_build.sh` or `./buildGuide.sh`; on build errors, fix draft and re-run Vale and build - -## Example Session - -```text -User: "Document feature from JIRA-456" -/gather → .artifacts/JIRA-456/01-context.md -/plan → .artifacts/JIRA-456/02-plan.md [user must approve before /draft] -/draft → .artifacts/JIRA-456/03-final-docs.adoc -/validate → vale; if fail → /draft then re-run /validate -/apply → repo .adoc files updated -/mr → merge request created -``` - -## Phases - -Systematic documentation creation through these phases: - -1. **Gather Context** (`/gather`) — Research the feature from Jira, GitHub, or a description -2. **Plan Structure** (`/plan`) — Determine where content belongs in the repository -3. **Draft Content** (`/draft`) — Write style-compliant AsciiDoc content -4. **Validate** (`/validate`) — Run Vale and optionally AsciiDoctor -5. **Apply Changes** (`/apply`) — Write validated content to repository files -6. **Create Merge Request** (`/mr`) — Create a GitLab merge request for the changes - -## Phase Transitions - -Each phase must meet its exit criteria before the next. If validation fails or the user requests changes, loop back: - -- `/gather` → proceed when context is saved to `01-context.md` -- `/plan` → proceed when plan is saved to `02-plan.md`; **stop for user approval** before `/draft` -- `/draft` → proceed when `03-final-docs.adoc` is written -- `/validate` → proceed when Vale (and optional AsciiDoctor) pass; if they fail, return to `/draft` and re-run `/validate` -- `/apply` → proceed when repository files are updated -- `/mr` → create merge request from the applied changes - -## File Layout - -The workflow controller lives at `skills/controller.md`. -It defines how to execute phases, recommend next steps, and handle transitions. -Phase skills are at `skills/{name}.md`. -Artifacts go in `.artifacts/${ticket_id}/`. +1. If the user invoked a specific command (e.g. `/draft`, `/validate`), read `commands/{command}.md` and follow it. +2. Otherwise, read `skills/controller.md` to load the workflow controller: + - If a `ticket_id` is known, check `.artifacts/${ticket_id}/` for existing artifacts and resume from the next incomplete phase (see "Resuming Work" in the controller) + - If the user provided a Jira ticket, GitHub issue URL, or feature description, execute the `/gather` phase + - Otherwise, execute the first phase the user requests + +If a step fails or produces unexpected output, stop and report the error to the +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/kcs/SKILL.md b/kcs/SKILL.md index 0dede1b..749c1b1 100644 --- a/kcs/SKILL.md +++ b/kcs/SKILL.md @@ -10,85 +10,13 @@ description: >- # KCS Article Workflow Orchestrator -When the user invokes a command, read `commands/{command}.md` for full -instructions. Otherwise, read `skills/controller.md` to determine which phase -to execute based on the user's input. +## Quick Start -## Phases +1. If the user invoked a specific command (e.g. `/draft`, `/validate`), read `commands/{command}.md` and follow it. +2. Otherwise, read `skills/controller.md` to determine which phase to execute based on the user's input. -| Phase | Command | Input | Output | -|-------|---------|-------|--------| -| Gather | `/gather` | Jira issue key/URL + user context | `01-context.md` | -| Draft | `/draft` | Context from Gather | `02-kcs-draft.md` | -| Validate | `/validate` | Draft from Draft | Updated draft with fixes | -| Handoff | `/handoff` | Validated draft | `03-handoff-message.md` | - -All artifacts: `.artifacts/kcs/{issue-key}/`. Advance only after user confirms. -Resolve all `/validate` blockers before `/handoff`. On failure: stop, report, -offer retry. - -## `/gather` - -1. Call Jira MCP `get_issue(issue_key="{key}")` — extract summary, description, - comments, linked issues. Read-only: never modify Jira. -2. Ask user for: symptoms, environment, workarounds, root cause. -3. Fill `templates/context.md` → write `01-context.md`. - -## `/draft` - -1. Load `01-context.md`. -2. Produce a markdown article with these sections and metadata: - -```markdown -# KCS Solution Draft — {ISSUE_KEY} -> **Article Type:** Solution -> **Article Confidence:** Not-Validated (WIP) -> **Product:** {PRODUCT_NAME_AND_VERSION} - -## Title -{Symptom + product name, one line, no brackets around product names} - -## Issue -{Customer-visible problem. Error messages in backticks or fenced blocks.} - -## Environment -- {Product and version per line, official names} - -## Diagnostic Steps -1. {One action per step, commands in fenced blocks, `` for values} - -## Resolution -**Workaround** (if not a permanent fix) -1. {Numbered steps, fenced commands, ends with verification step} - -## Root Cause -{Technical mechanism. Link Jira ticket tracking permanent fix.} -``` - -1. Style rules: present tense, no personal pronouns, backticks for paths / - commands / config keys, fenced code blocks for commands and output, en-US - spelling. See `templates/section-guidance.md` for full per-section rules. -2. Write `02-kcs-draft.md`. - -## `/validate` - -Load `02-kcs-draft.md` and check against `templates/validation-checklist.md`: - -- All sections present and non-empty (Title, Issue, Environment, Diagnostic - Steps, Resolution, Root Cause) -- Title: one line, describes symptom + product, no prefix -- Issue: customer perspective, no workaround content, no internal links -- Diagnostic Steps: numbered, one action each, commands in fenced blocks -- Resolution: workarounds labeled, ends with verification, no internal links -- Style: present tense, no pronouns, backticks for technical terms - -Fix violations inline. List remaining issues for the user. - -## `/handoff` - -1. Load validated `02-kcs-draft.md`. -2. Compose message for the support engineer: article text, open items, next - steps (publish to portal, set confidence level). -3. Write `03-handoff-message.md`, show to user before they send. +If a step fails or produces unexpected output, stop and report the error to the +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. For principles, hard limits, and quality rules, see `guidelines.md`. diff --git a/skill-reviewer/SKILL.md b/skill-reviewer/SKILL.md index 2a6e4d2..9968cce 100644 --- a/skill-reviewer/SKILL.md +++ b/skill-reviewer/SKILL.md @@ -10,52 +10,10 @@ description: >- ## Quick Start -Run `/review` to execute the full workflow. The user must specify which skill directory to review (e.g. `bugfix/`, `docs-writer/`). Executable without opening other files: +1. If the user invoked `/review`, read `commands/review.md` and follow it. +2. Otherwise, the user must specify which skill directory to review (e.g. `bugfix/`, `docs-writer/`). Read `skills/review.md` to execute the review. -1. Read every file in the target skill directory: `SKILL.md`, `skills/*.md`, `commands/*.md`, `guidelines.md`, `README.md`. If the directory doesn't exist or has no skill files, report the error and stop. Note any missing files — gaps are themselves a finding. -2. Evaluate against 8 dimensions: - - **Orchestration & Routing** — correct routing, no orphaned/dangling references, executable Quick Start - - **Step Sequencing** — sequential numbering, correct cross-references, logical order - - **Schema Consistency** — matching field names/types across files, schema visible before first use - - **Cognitive Load** — flag skills with >10 steps, synthesis after heavy processing, missing batching - - **Instruction Clarity** — unambiguous, first-try-correct, clear when-to-use vs when-to-skip - - **Documentation & Project Alignment** — README matches implementation, consistent with sibling skills and project conventions - - **Command Naming** — consistent pattern (verbs vs nouns), self-explanatory - - **Error Handling** — failure modes documented, escalation paths clear -3. Classify each finding by severity — **CRITICAL** / **HIGH** (blockers) or **MEDIUM** / **LOW** (suggestions). -4. Validate findings: verify each finding cites a specific file, includes a concrete suggestion, and that blocker/suggestion counts are accurate. Drop any finding you cannot substantiate from the files you read. -5. Produce a structured report and write it to `.artifacts/skill-reviewer/{skill-name}/review.md`: +If a step fails or produces unexpected output, stop and report the error to the +user. -``` -## Skill Review: {skill-name} - -[2-3 sentence overall assessment] - -### Strengths -- [What's well-done] - -### Findings - -| # | Severity | File | Finding | Suggestion | -|---|----------|------|---------|------------| -| 1 | HIGH | skills/scan.md | ... | ... | - -### Summary - -- **Blockers**: {count} -- **Suggestions**: {count} -- **Verdict**: [one-line summary] -``` - -## File Layout - -```text -skill-reviewer/ - SKILL.md # This file — workflow overview and routing - guidelines.md # Principles, hard limits, safety, quality standards - README.md # User-facing documentation - commands/ - review.md # /review command — loads guidelines + skill - skills/ - review.md # The review skill (detailed steps and output format) -``` +For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/triage/SKILL.md b/triage/SKILL.md index 4d0ffca..2bb2efc 100644 --- a/triage/SKILL.md +++ b/triage/SKILL.md @@ -18,65 +18,8 @@ description: >- 4. If the user provided a Jira project key but no specific command, start with `skills/scan.md` 5. If no project key was provided, start with `skills/start.md` to gather it -Each phase skill (e.g. `skills/scan.md`) follows this pattern: - -1. Announce the phase: *"Starting /scan."* -2. Execute the skill's steps — query Jira, analyze issues, write artifacts -3. Write output to the artifact directory and present on-completion recommendations - -## Example: Running /scan - -To execute the scan phase without opening external files: - -1. `mkdir -p .artifacts/triage/EDM` -2. Call the MCP tool `jira_search` (server: `user-mcp-jira`) with JSON arguments: - ```json - {"jql": "project = EDM AND issuetype = Bug AND resolution = Unresolved ORDER BY key ASC", "fields": "summary,status,priority,assignee,reporter,created,updated,labels,components,description", "limit": 50} - ``` -3. Paginate with JQL cursor: add `AND key > '{last_key}'` to the JQL using the last issue key from the previous page. Stop when a page returns fewer than 50 issues. -4. Write unresolved issues to `.artifacts/triage/EDM/issues.json` -5. Run the resolved-bug JQL from `skills/scan.md` (Fetch Recently Resolved Bugs step) and write `.artifacts/triage/EDM/resolved.json` - -## Example Session - -```text -User: "Triage unresolved bugs in EDM" - -/start → validates Jira access for project EDM -/scan → fetches unresolved bugs + recently resolved bugs (90d window) - → writes .artifacts/triage/EDM/issues.json and resolved.json -/analyze → categorizes each bug; error signatures, duplicate confidence, regressionOf - → reads resolved.json for regression hints; writes analyzed.json -/report → generates interactive HTML dashboard - → writes .artifacts/triage/EDM/report.html - -/assess → (separate) full triage of one issue in chat — read skills/assess.md -``` - -## Phases - -- **Run** (`/run`) — Execute all bulk phases below end-to-end without pausing - -1. **Start** (`/start`) — Validate Jira access, confirm project key -2. **Scan** (`/scan`) — Fetch all unresolved bugs and recently resolved bugs via JQL with pagination; write `issues.json` and `resolved.json` -3. **Analyze** (`/analyze`) — Categorize each bug with recommendation, error signature, `duplicateConfidence`, `regressionOf` (using `resolved.json`), reason, confidence, and auto-fix likelihood where applicable -4. **Report** (`/report`) — Generate a self-contained interactive HTML report - -- **Assess** (`/assess`) — Not part of the bulk sequence. Deep triage for **one** issue (see `skills/assess.md`); no `analyzed.json` / `report.html` unless the user runs bulk `/analyze` / `/report` afterward. - -## Phase Transitions - -Each phase must meet its exit criteria before the next. If a phase fails, stop and report the error. - -- `/start` → proceed when Jira access is validated and project key is confirmed. If access fails (auth error, unknown project), stop and report. -- `/scan` → proceed when all unresolved bugs are fetched and `issues.json` is saved, and `resolved.json` is written (may be empty). Verify: unresolved count in `issues.json` matches Jira. If **zero unresolved** issues, stop — the project key or issue type may be wrong. -- `/analyze` → proceed when every issue has a recommendation and `analyzed.json` is written. Verify: the number of analyzed issues matches the scanned unresolved count. If `issues.json` is missing, run `/scan` first. If `resolved.json` is missing, analyze may still run (regression matching uses an empty resolved list). -- `/report` → done when the HTML report is written. If `analyzed.json` is missing, run `/analyze` first. - -## File Layout - -Phase skills are at `skills/{name}.md`. Each skill is self-contained with its own instructions, allowed tools, and on-completion recommendations. -The HTML template is at `templates/report.html`. -Artifacts go in `.artifacts/triage/{project}/`. +If a step fails or produces unexpected output, stop and report the error to the +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/triage/guidelines.md b/triage/guidelines.md index 210a1eb..4bad58b 100644 --- a/triage/guidelines.md +++ b/triage/guidelines.md @@ -65,3 +65,19 @@ Stop and request human guidance when: - The scan returns zero **unresolved** bugs (possibly wrong project key or issue type) - More than 30% of issues lack descriptions (data quality problem, not a triage problem) - The user asks to modify Jira issues (out of scope for this workflow) + +## Example Session + +```text +User: "Triage unresolved bugs in EDM" + +/start → validates Jira access for project EDM +/scan → fetches unresolved bugs + recently resolved bugs (90d window) + → writes .artifacts/triage/EDM/issues.json and resolved.json +/analyze → categorizes each bug; error signatures, duplicate confidence, regressionOf + → reads resolved.json for regression hints; writes analyzed.json +/report → generates interactive HTML dashboard + → writes .artifacts/triage/EDM/report.html + +/assess → (separate) full triage of one issue in chat — read skills/assess.md +``` From 7656dcb8a1cbde6ae45c61f330f39bbb43e100ea Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Sat, 2 May 2026 14:23:46 +0300 Subject: [PATCH 2/6] Fix CodeRabbit's review comments --- bugfix/SKILL.md | 2 +- bugfix/guidelines.md | 2 +- cve-fix/guidelines.md | 2 ++ skill-reviewer/SKILL.md | 5 +++-- triage/SKILL.md | 2 +- triage/guidelines.md | 2 ++ 6 files changed, 10 insertions(+), 5 deletions(-) diff --git a/bugfix/SKILL.md b/bugfix/SKILL.md index cf5c12d..3767f29 100644 --- a/bugfix/SKILL.md +++ b/bugfix/SKILL.md @@ -13,7 +13,7 @@ description: >- ## Quick Start 1. If the user invoked a specific command (e.g. `/unattended`, `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. -2. If the user invoked `/unattended`, read `skills/unattended.md` — this runs diagnose → fix → test → review to completion without human input. +2. If the user invoked `/unattended`, read `skills/unattended.md` — this runs the unattended bugfix workflow to completion without human input. 3. Otherwise, read `skills/controller.md` to load the workflow controller: - If the user provided a bug report or issue URL, execute the `/assess` phase - Otherwise, execute `/start` to present available phases diff --git a/bugfix/guidelines.md b/bugfix/guidelines.md index 1ffe327..a902493 100644 --- a/bugfix/guidelines.md +++ b/bugfix/guidelines.md @@ -76,7 +76,7 @@ User: "Fix issue #421 — NullPointerException on login" → writes .artifacts/bugfix/421/root-cause.md /fix → adds null-check, minimal diff /test → regression test passes ✓ - → if tests fail → return to /fix + → if tests fail: stop and report; offer retry of /fix or escalation /pr → pushes branch, creates draft PR ``` diff --git a/cve-fix/guidelines.md b/cve-fix/guidelines.md index 181da43..4e0dd10 100644 --- a/cve-fix/guidelines.md +++ b/cve-fix/guidelines.md @@ -100,3 +100,5 @@ User: *"Fix vulnerability EDM-1234"* 4. `/pr` — `git checkout -b cve-fix/EDM-1234`, then `gh pr create --draft --base main` → draft PR 5. `/backport` — cherry-pick to `release-2.16`, create backport PR → writes `backport-log.md` 6. `/close` — verify PRs merged, update Jira tickets to ON_QA → writes `close-report.md` + +If any step fails or produces unexpected output: stop, report the error, and offer retry or escalation. diff --git a/skill-reviewer/SKILL.md b/skill-reviewer/SKILL.md index 9968cce..250d6ea 100644 --- a/skill-reviewer/SKILL.md +++ b/skill-reviewer/SKILL.md @@ -11,9 +11,10 @@ description: >- ## Quick Start 1. If the user invoked `/review`, read `commands/review.md` and follow it. -2. Otherwise, the user must specify which skill directory to review (e.g. `bugfix/`, `docs-writer/`). Read `skills/review.md` to execute the review. +2. Otherwise, if no skill directory was specified, ask the user which directory to review (e.g. `bugfix/`, `docs-writer/`). Then read `skills/review.md` to execute the review. If a step fails or produces unexpected output, stop and report the error to the -user. +user. Do not advance to the next phase. Offer to retry the failed step or +escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. diff --git a/triage/SKILL.md b/triage/SKILL.md index 2bb2efc..10a2a92 100644 --- a/triage/SKILL.md +++ b/triage/SKILL.md @@ -15,7 +15,7 @@ description: >- 1. If the user invoked `/run`, read `skills/run.md` and follow it — this drives all phases end-to-end without pausing 2. If the user invoked `/assess`, read `skills/assess.md` and follow it — full single-issue triage in chat (does not write `analyzed.json` / `report.html`) 3. If the user invoked a specific bulk phase command (`/start`, `/scan`, `/analyze`, `/report`), read the corresponding skill file from `skills/{phase}.md` and execute it -4. If the user provided a Jira project key but no specific command, start with `skills/scan.md` +4. If the user provided a Jira project key but no specific command, start with `skills/start.md` to validate access and create the workspace, then proceed to `skills/scan.md` 5. If no project key was provided, start with `skills/start.md` to gather it If a step fails or produces unexpected output, stop and report the error to the diff --git a/triage/guidelines.md b/triage/guidelines.md index 4bad58b..010707e 100644 --- a/triage/guidelines.md +++ b/triage/guidelines.md @@ -80,4 +80,6 @@ User: "Triage unresolved bugs in EDM" → writes .artifacts/triage/EDM/report.html /assess → (separate) full triage of one issue in chat — read skills/assess.md + +If any step fails or produces unexpected output: stop, report the error, and offer retry or escalation. ``` From ed0409bd0584e833c06650bf630ca107c0782165 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Wed, 6 May 2026 14:46:03 +0300 Subject: [PATCH 3/6] Fix review comments --- bugfix/SKILL.md | 2 +- cve-fix/guidelines.md | 2 -- triage/guidelines.md | 2 -- 3 files changed, 1 insertion(+), 5 deletions(-) diff --git a/bugfix/SKILL.md b/bugfix/SKILL.md index 3767f29..2b5cb83 100644 --- a/bugfix/SKILL.md +++ b/bugfix/SKILL.md @@ -12,7 +12,7 @@ description: >- ## Quick Start -1. If the user invoked a specific command (e.g. `/unattended`, `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. +1. If the user invoked a specific command (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. 2. If the user invoked `/unattended`, read `skills/unattended.md` — this runs the unattended bugfix workflow to completion without human input. 3. Otherwise, read `skills/controller.md` to load the workflow controller: - If the user provided a bug report or issue URL, execute the `/assess` phase diff --git a/cve-fix/guidelines.md b/cve-fix/guidelines.md index 4e0dd10..181da43 100644 --- a/cve-fix/guidelines.md +++ b/cve-fix/guidelines.md @@ -100,5 +100,3 @@ User: *"Fix vulnerability EDM-1234"* 4. `/pr` — `git checkout -b cve-fix/EDM-1234`, then `gh pr create --draft --base main` → draft PR 5. `/backport` — cherry-pick to `release-2.16`, create backport PR → writes `backport-log.md` 6. `/close` — verify PRs merged, update Jira tickets to ON_QA → writes `close-report.md` - -If any step fails or produces unexpected output: stop, report the error, and offer retry or escalation. diff --git a/triage/guidelines.md b/triage/guidelines.md index 010707e..4bad58b 100644 --- a/triage/guidelines.md +++ b/triage/guidelines.md @@ -80,6 +80,4 @@ User: "Triage unresolved bugs in EDM" → writes .artifacts/triage/EDM/report.html /assess → (separate) full triage of one issue in chat — read skills/assess.md - -If any step fails or produces unexpected output: stop, report the error, and offer retry or escalation. ``` From fd72dc0d81e1579c9592310f427cd5a1848f9f67 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Wed, 6 May 2026 14:59:57 +0300 Subject: [PATCH 4/6] Fix review comments 2 --- bugfix/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bugfix/SKILL.md b/bugfix/SKILL.md index 2b5cb83..3259073 100644 --- a/bugfix/SKILL.md +++ b/bugfix/SKILL.md @@ -12,7 +12,7 @@ description: >- ## Quick Start -1. If the user invoked a specific command (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. +1. If the user invoked a phase command other than `/unattended` (e.g. `/diagnose`, `/fix`), read `commands/{command}.md` and follow it. 2. If the user invoked `/unattended`, read `skills/unattended.md` — this runs the unattended bugfix workflow to completion without human input. 3. Otherwise, read `skills/controller.md` to load the workflow controller: - If the user provided a bug report or issue URL, execute the `/assess` phase From 31b15a3a80ca9d3e05cfad73caf34c7123157174 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Wed, 6 May 2026 17:53:26 +0300 Subject: [PATCH 5/6] Fix lint failure --- skill-reviewer/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skill-reviewer/SKILL.md b/skill-reviewer/SKILL.md index edb43f6..ac1279e 100644 --- a/skill-reviewer/SKILL.md +++ b/skill-reviewer/SKILL.md @@ -13,7 +13,6 @@ description: >- 1. If the user invoked `/review`, read `commands/review.md` and follow it. 2. Otherwise, if no skill directory was specified, ask the user which directory to review (e.g. `bugfix/`, `docs-writer/`). Then read `skills/review.md` to execute the review. -<<<<<<< skill-updates If a step fails or produces unexpected output, stop and report the error to the user. Do not advance to the next phase. Offer to retry the failed step or escalate. @@ -72,4 +71,3 @@ skill-reviewer/ scripts/ pre-review-checks.py # Automated structural/reference/sequencing checks ``` ->>>>>>> main From 615dae073f57863cc363d8be08a4c82cd0639a97 Mon Sep 17 00:00:00 2001 From: Amir Yogev Date: Wed, 6 May 2026 18:00:04 +0300 Subject: [PATCH 6/6] Fix lint failure 2 --- skill-reviewer/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skill-reviewer/SKILL.md b/skill-reviewer/SKILL.md index ac1279e..138991a 100644 --- a/skill-reviewer/SKILL.md +++ b/skill-reviewer/SKILL.md @@ -18,7 +18,7 @@ user. Do not advance to the next phase. Offer to retry the failed step or escalate. For principles, hard limits, safety, quality, and escalation rules, see `guidelines.md`. -======= + 1. Read every file in the target skill directory: `SKILL.md`, `skills/*.md`, `commands/*.md`, `guidelines.md`, `README.md`. If the directory doesn't exist or has no skill files, report the error and stop. Note any missing files — gaps are themselves a finding. 2. Run automated pre-review checks: `python3 {skill-reviewer-dir}/scripts/pre-review-checks.py {target-dir}` — captures structural, frontmatter, reference, and sequencing issues deterministically. Treat `FAIL` results as pre-validated findings; apply judgment to `WARN` results. If the script is not present, skip and check manually. 3. Evaluate against 8 dimensions (use automated check results as pre-validated evidence where available): @@ -34,7 +34,7 @@ For principles, hard limits, safety, quality, and escalation rules, see `guideli 5. Validate findings: verify each finding cites a specific file, includes a concrete suggestion, and that blocker/suggestion counts are accurate. Drop any finding you cannot substantiate from the files you read. 6. Produce a structured report and write it to `.artifacts/skill-reviewer/{skill-name}/review.md`: -``` +```text ## Skill Review: {skill-name} [2-3 sentence overall assessment]