Reduce the size and remove duplicate content on oversized SKILL.MD files

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 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
    - 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 <file>` and `git log --oneline -10 -- <file>`
-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`.

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: stop and report; offer retry of /fix or escalation
+/pr        → pushes branch, creates draft PR
+```
+
 ## Working With the Project
 
 This workflow gets deployed into different projects. Respect the target project:

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`.

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`

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 <num> --repo <owner/repo>`); capture description, acceptance criteria, comments
-3. Find linked PRs (e.g. titles with `[JIRA-123]`), fetch diffs with `gh pr diff <num> --repo <owner/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`.

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, `<PLACEHOLDER>` 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`.