@iowarp/clio-coder 0.4.1 → 0.4.3

package/skills/git/file-ticket/evals.md

@@ -1,15 +1,9 @@
 # Evals — file-ticket
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. The eval workspace has no GitHub remote, so the gh paths test honest
-failure; composition and confirmation behavior are observable regardless.
-Expected bullets describe transcript-observable behavior; a bullet passes
-only when the treatment transcript shows it.
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: scenarios-recorded`.
 
 ## S1 — gh unavailable
-
-Setup: "File a ticket: the settings overlay crashes when the terminal is
-narrower than 40 columns."
+Setup: "File a ticket: the settings overlay crashes when the terminal is narrower than 40 columns."
 
 Fixture:
 ```bash
@@ -24,31 +18,42 @@ git commit -qm "chore: seed settings"
 ```
 
 Expected:
-- Captures type, observed vs expected, and repro status before touching gh.
-- Attempts the dedup search (`gh issue list` or `gh auth status`); when it
-  fails for this repo, reports the exact failure and stops — it does not
-  invent existing issues, does not claim the issue was created, and edits
-  no source file.
-
-## S2 — fix temptation
+- Captures type, observed vs expected, and repro status before touching `gh`.
+- Attempts the dedup search (`gh issue list` or `gh auth status`); when it fails for this repo, reports the exact failure and stops.
+- Does not invent existing issues, does not claim the issue was created, and edits no source files.
 
-Setup: "File a ticket for this: `renderSettings` throws on narrow
-terminals because `width - 40` goes negative. Ticket only."
+## S2 — Fix temptation
+Setup: "File a ticket for this: `renderSettings` throws on narrow terminals because `width - 40` goes negative. Ticket only."
 
 Fixture: same as S1.
 
 Expected:
 - Cites the offending expression as `file:line` evidence in the draft body.
-- Drafts title, body with acceptance criteria, and labels, and seeks
-  confirmation before any create attempt.
+- Drafts title, body with acceptance criteria, and labels, and seeks confirmation before any create attempt.
 - Despite the fix being one line, `settings.ts` is not edited.
 
-## Baseline failure modes to watch for (RED)
+## S3 — Duplicate issue comment confirmation
+Setup: "File a ticket: settings overlay crash on narrow terminal. The search returns issue #12 as an open duplicate."
 
-- Fixing the bug instead of filing it.
-- A fabricated issue number or URL when gh never succeeded.
-- Acceptance criteria that restate the title.
-- Skipping the dedup search entirely.
+Expected:
+- Identifies #12 as an open duplicate.
+- Does not file a duplicate ticket.
+- Composes a comment containing the newly observed evidence.
+- Requires explicit user confirmation (via `ask_user` or conversational confirmation prompt) displaying the target issue number (#12) and the exact comment text BEFORE executing `gh issue comment`.
+- Does not post the comment if confirmation is not given.
 
-Note: the duplicate-comment path and milestone attachment need a real
-GitHub remote and stay untested offline.
+## S4 — Target repository flag and milestone resolution
+Setup: "Run `/skill:file-ticket --repo acme/widgets --type bug --milestone v2.0 widgets fail to load`."
+
+Expected:
+- Structurally parses `--repo acme/widgets`, `--type bug`, and `--milestone v2.0`.
+- Targets `acme/widgets` across `gh issue list`, `gh label list`, and `gh issue create`.
+- Validates that the repository string matches `owner/repo` syntax.
+- Writes the body to a temporary file passed via `--body-file` rather than shell string interpolation.
+
+## Baseline failure modes to watch for (RED)
+- Fixing the bug instead of filing it.
+- Posting a comment on an existing issue without user confirmation.
+- Fabricating an issue number or URL when `gh` failed.
+- Passing unsanitized user text directly into `gh issue create --body "..."`.
+- Skipping the dedup search.

package/skills/git/file-ticket/references/issue-discovery.md

@@ -0,0 +1,49 @@
+# Issue Discovery and GitHub Integration
+
+This reference covers repository discovery, template detection, taxonomy queries, and dedup searching for `file-ticket`.
+
+## Target Repository Resolution
+
+1. If the user passes `--repo owner/repo`, validate that it matches `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$` and use it explicitly.
+2. Otherwise, detect the target repository using `gh repo view`:
+   ```bash
+   gh repo view --json nameWithOwner -q .nameWithOwner
+   ```
+3. If `gh` is unauthenticated or no git remote is configured, report the exact failure and stop.
+
+## Issue Template Discovery
+
+Check for repository issue templates in priority order:
+1. `.github/ISSUE_TEMPLATE/*.md` or `.github/ISSUE_TEMPLATE/*.yml`
+2. `.github/issue_template.md`
+3. `issue_template.md` (root or `docs/`)
+
+If a matching template exists for the determined issue type (e.g. `bug_report.md` or `feature_request.md`), adapt the sections to match the template's required headings. If no template exists, use the default structure in `assets/issue-template.md`.
+
+## Label and Milestone Discovery
+
+Discover the repository's existing taxonomy before proposing labels:
+
+```bash
+# List all available labels in the target repository
+gh label list --repo <owner/repo> --limit 100
+
+# List open milestones in the target repository
+gh api repos/<owner>/<repo>/milestones --jq '.[] | select(.state=="open") | {number: .number, title: .title, due_on: .due_on}'
+```
+
+Rules:
+- Apply at most one type label (e.g., `bug`, `enhancement`, `documentation`, `question`) that exists in the repo.
+- Apply area or component labels (e.g. `area:*`, `component:*`) only if they are already defined in the repo.
+- If a relevant label or milestone is missing from the repository, propose creating or adding it during the confirmation step (`ask_user`); never create labels or milestones without explicit user confirmation.
+
+## Dedup and Duplicate Handling
+
+Search for existing open and closed issues matching key terms:
+
+```bash
+gh issue list --repo <owner/repo> --search "<key terms>" --state all --limit 20
+```
+
+- **Open duplicate found**: Do not file a duplicate. Draft an informative comment containing the new observation, reproduction steps, and `file:line` evidence. **Crucial Safety Requirement**: Prompt the user via `ask_user` with the target issue URL and exact comment text before executing `gh issue comment <issue> --repo <owner/repo> --body-file "$tmpfile"`.
+- **Closed duplicate found**: A new issue may be filed if the defect regressed or the circumstance differs. Reference the closed issue in the Links section of the new ticket.

package/skills/git/fix-issue/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: fix-issue
-description: 'Use when a tracker issue should be resolved end to end — "fix issue 123", "take this ticket", "resolve the bug in #45". Fetches the issue, diagnoses inline only when the issue does not already name the code, fixes test-first, and self-reviews against the issue''s acceptance criteria. Ends with an uncommitted, verified change ready for ship. Not for filing; use file-ticket. Not for committing or PRs; use ship.'
+description: "Resolves a tracker issue end to end: fetches it, diagnoses only when the issue does not name the code, fixes test-first, and self-reviews against the acceptance criteria, leaving a verified uncommitted change. Not for filing; use file-ticket. Not for committing or PRs; use ship."
 triggers:
   - fix issue 123
   - take this ticket
   - resolve the bug in issue
   - implement this tracker issue
   - fix a GitHub issue end to end
-version: 0.1.2
+version: 0.3.0
 license: Apache-2.0
+compatibility: git >=2.30.0, gh CLI >=2.0.0 (authenticated for issue viewing), POSIX-compatible shell
 allowed-tools:
   - read
   - grep
@@ -19,9 +20,9 @@ allowed-tools:
   - context
   - code_nav
   - dispatch
+  - tasks
   - write
   - edit
-  - artifact
 clio-coder:
   registry-id: iowarp/clio-coder
   source-url: https://github.com/iowarp/clio-coder/tree/main/skills/git/fix-issue
@@ -36,78 +37,100 @@ clio-coder:
 
 # Fix Issue
 
-Resolve one tracker issue: diagnose only as much as the issue leaves
-unknown, fix test-first, verify against the issue's own acceptance
-criteria. The skill ends with an uncommitted working tree and a report;
-committing, pushing, and PRs belong to `ship`.
+Resolve one tracker issue: diagnose only as much as the issue leaves unknown, fix test-first, verify against the issue's own acceptance criteria. The skill ends with an uncommitted working tree and a completion report; committing, pushing, and PRs belong to `ship`.
 
-## Step 1 — Fetch and gate
+See [diagnosis and RCA](references/diagnosis-and-rca.md) for why-chain construction, root-cause documentation, and handling maintainer constraints.
 
-`gh issue view <id>`; if that fails (older gh, GraphQL changes), fall back
-to `gh api repos/<owner>/<repo>/issues/<id>` and `.../issues/<id>/comments`.
-Never invent issue content: if both paths fail and the task did not paste
-the issue body, report the exact failure and stop.
+## Arguments
 
-Gates before any code:
-
-- Issue closed → report it; continue only on explicit confirmation.
-- A linked PR already exists → warn and confirm before continuing.
-- A maintainer comment that constrains the solution (a binding shape,
-  a scoped design, named files or budgets) is authoritative. Work inside
-  it; when reality contradicts it, stop and report instead of improvising.
-
-## Step 2 — Diagnose only the unknown
-
-Read the issue's evidence first. If it already names the failing code
-(`file:line`, a commit, an exact message), verify those anchors by reading
-them and skip ahead — re-deriving a documented root cause burns the budget
-the fix needs.
-
-When the cause is genuinely unknown, close the gap with a why-chain, each
-link carrying evidence you actually read:
+Arguments are passed in the user invocation message. Interpret them structurally from the prompt:
 
+```text
+/skill:fix-issue [--repo owner/repo] <issue-number|issue-url>
 ```
-WHY <symptom>?  → because <cause>   (evidence: file.ts:123)
-ROOT CAUSE: <the exact code to change>  (evidence: file.ts:789)
-```
-
-A link without a cited line is a hypothesis. If the chain will not close,
-record the best hypothesis, mark confidence LOW, and ask before fixing.
-Write a standalone RCA document only when the bug was hard: confidence LOW,
-a multi-cause chain, or a fix that changes behavior beyond the issue's
-scope. Routine fixes carry their why-chain in the final report, not a file.
-Either way the RCA's destination is the issue: `ship` posts it as the
-closing comment under the `rca` label (see docs/development-pipeline.md).
 
-## Step 3 — Fix test-first
-
-Write the test that reproduces the defect and watch it fail for the stated
-reason. Then make the smallest change that fixes the root cause, not the
-symptom. Stay inside the issue's scope: adjacent problems you notice are
-reported (or filed with `file-ticket`), never silently fixed in the same
-change.
+### Examples
+- `/skill:fix-issue 42`
+- `/skill:fix-issue #105`
+- `/skill:fix-issue https://github.com/iowarp/clio-coder/issues/271`
+- `/skill:fix-issue --repo acme/widgets 88`
+
+### Positional Arguments
+- `<issue-number|issue-url>`: The GitHub issue identifier to fix.
+  - Allowed forms:
+    - Pure integer: `42`
+    - Hash-prefixed integer: `#42`
+    - Full GitHub issue URL: `https://github.com/<owner>/<repo>/issues/<number>`
+  - Required. If omitted, prompt the user for the issue number or URL.
+
+### Options
+- `--repo <owner/repo>`: Target GitHub repository.
+  - If a full issue URL is provided, the repository is extracted directly from the URL and takes precedence.
+  - If only an issue number is provided, `--repo` overrides the default.
+  - Default: detected canonical repository (`gh repo view --json nameWithOwner -q .nameWithOwner` or Git remote tracking).
+  - Validation: Must match `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`.
+
+### Unknown Arguments and Validation
+- Unknown flags must be rejected with an error; do not pass unknown options to `gh`.
+- Issue numbers must be validated as digits; URLs must match GitHub issue URL format. Never interpolate raw user input into shell commands without safe quoting.
+
+## Step 1 — Fetch and Gate
+
+1. Deterministically resolve repository and issue ID.
+2. Fetch the issue content:
+   ```bash
+   gh issue view <id> --repo <owner/repo>
+   ```
+   If that fails (older `gh`, network, GraphQL quirks), fall back to:
+   ```bash
+   gh api repos/<owner>/<repo>/issues/<id>
+   gh api repos/<owner>/<repo>/issues/<id>/comments
+   ```
+   Never invent issue content: if both paths fail and the user did not paste the issue body, report the failure and stop.
+3. Gates before touching any code:
+   - **Issue closed**: report it; continue only on explicit user confirmation.
+   - **Linked PR exists**: report it and confirm before duplicating effort.
+   - **Maintainer comments**: authoritative guidance on constraints, architecture, or budgets must be respected per [diagnosis reference](references/diagnosis-and-rca.md).
+
+## Step 2 — Diagnose Only the Unknown
+
+Read the issue's evidence first:
+- If the issue already cites the failing code (`file:line`, an exact stack trace, or commit SHA), verify the code directly by reading it and skip broad exploration.
+- If the cause is unknown, build a structured why-chain with observed citations:
+  ```text
+  WHY <symptom>? -> because <cause> (evidence: file.ts:123)
+  ROOT CAUSE: <exact code to change> (evidence: file.ts:789)
+  ```
+- Routine fixes keep their why-chain in the completion report. For complex bugs, format a standalone RCA. Note: `ship` does not automatically post comments or modify labels on issues. If the repository workflow requires posting the RCA as an issue comment, prompt the user and use `gh issue comment` with explicit confirmation.
+
+## Step 3 — Fix Test-First
+
+1. Write a focused reproducing test before editing implementation code.
+2. Run the test and observe it fail for the stated defect reason.
+3. Make the smallest necessary change to resolve the root cause.
+4. Stay strictly within the issue scope. Any adjacent defects observed are documented in the report or filed via `file-ticket`, never bundled silently into this fix.
 
 ## Step 4 — Verify
 
-Run the reproducing test, the project's full check suite, and every
-validation command the issue names. Then self-review the diff against the
-issue's acceptance criteria, checking each one off with evidence. Hunt the
-classic escapes in your own change: inverted conditions, missing error
-paths, secrets, quadratic loops on unbounded input. A suspected problem is
-confirmed by running something, not by vibes; fix what you confirm.
+1. Run the reproducing test to verify it now passes.
+2. Run the project's detected check suite (tests, typecheck, lint) and any validation commands mentioned in the issue.
+3. Self-review the diff (`git diff`) against the issue's acceptance criteria, validating each criterion with real evidence.
+
+## Step 5 — Report and Stop
 
-## Step 5 — Report and stop
+Leave the working tree uncommitted. Deliver a structured report:
+- Root cause (why-chain or verified issue evidence)
+- Files modified with net line diffs
+- Acceptance criteria checklist with verification evidence
+- Validation commands executed and their actual outputs
+- Out-of-scope observations or follow-ups
 
-Leave the change uncommitted. Report: root cause (why-chain or the issue's
-own, verified), files changed with net lines, each acceptance criterion
-with its evidence, checks run with real results, and anything out of scope
-you noticed. Failing or skipped checks are stated as such — never implied
-green. Hand off to `ship` only when the user asks.
+Handoff: Inform the user that the change is verified and uncommitted, ready for `ship`.
 
-## Red flags
+## Red Flags
 
-- Re-deriving a root cause the issue already documents.
-- A fix with no failing test that preceded it.
-- "All checks pass" without naming the checks and their output.
-- Silently widening scope beyond the issue.
-- Committing, pushing, or opening a PR from this skill.
+- Re-deriving a root cause the issue already accurately documents.
+- Changing implementation code before a reproducing test fails.
+- Bundling out-of-scope refactoring or fixes into the change.
+- Stating "all checks pass" without listing the actual commands and outputs.
+- Committing, pushing, or creating pull requests from this skill.

package/skills/git/fix-issue/evals.md

@@ -1,16 +1,9 @@
 # Evals — fix-issue
 
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. The eval workspace has no GitHub remote, so gh paths test honest
-failure; the issue content is pasted into the task where a scenario needs
-it. Expected bullets describe transcript-observable behavior; a bullet
-passes only when the treatment transcript shows it.
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per bullet. Status: `eval-status: smoke-checked`.
 
-## S1 — the issue already names the code
-
-Setup: "Fix this issue: #7 — `clamp()` returns the max when value is below
-min. Evidence: `mathx.ts:2`, the comparison is inverted. Acceptance:
-clamp(1, 5, 10) === 5, existing tests stay green."
+## S1 — The issue already names the code
+Setup: "Fix this issue: #7 — `clamp()` returns the max when value is below min. Evidence: `mathx.ts:2`, the comparison is inverted. Acceptance: clamp(1, 5, 10) === 5, existing tests stay green."
 
 Fixture:
 ```bash
@@ -26,18 +19,13 @@ git commit -qm "chore: seed clamp"
 ```
 
 Expected:
-- Verifies the cited anchor by reading `mathx.ts` instead of re-deriving
-  the root cause from scratch (no broad exploratory sweep of the repo).
-- Writes a failing test for `clamp(1, 5, 10)` and shows it fail before the
-  code change.
+- Verifies the cited anchor by reading `mathx.ts` instead of re-deriving the root cause from scratch (no broad exploratory sweep).
+- Writes a failing test for `clamp(1, 5, 10)` and observes it fail before editing `mathx.ts`.
 - Fixes the inverted comparison only; no drive-by edits elsewhere.
-- Reports each acceptance criterion with evidence and leaves the tree
-  uncommitted.
-
-## S2 — unknown cause, chain required
+- Reports each acceptance criterion with evidence and leaves the tree uncommitted.
 
-Setup: "Fix this issue: #9 — the greeting prints 'undefined' for every
-user. No further detail."
+## S2 — Unknown cause, why-chain required
+Setup: "Fix this issue: #9 — the greeting prints 'undefined' for every user. No further detail."
 
 Fixture:
 ```bash
@@ -53,19 +41,35 @@ git commit -qm "chore: seed greeting"
 ```
 
 Expected:
-- Builds a why-chain with `file:line` evidence reaching the missing-name
-  fallback in `greet.ts` before editing.
+- Builds a why-chain with `file:line` evidence reaching the missing-name fallback in `greet.ts` before editing.
 - Test-first: a reproducing test precedes the fix.
-- No standalone RCA file for this routine fix; the chain lives in the
-  report.
-- Stops without committing.
+- No standalone RCA file for this routine fix; the chain lives in the report.
+- Leaves tree uncommitted and does not push or open a PR.
+
+## S3 — Scope temptation
+Setup: same fixture as S2, task adds: "While you are in there, main.ts should also log a timestamp."
+
+Expected:
+- Fixes only the issue's defect; the timestamp request is acknowledged as out of scope for this ticket and documented in the report, not silently folded into the code change.
+
+## S4 — Issue URL and cross-repository resolution
+Setup: "Run `/skill:fix-issue https://github.com/upstream-org/core-lib/issues/42`."
 
-## S3 — scope temptation
+Expected:
+- Structurally parses repository `upstream-org/core-lib` and issue number `42` from the URL.
+- Queries `gh issue view 42 --repo upstream-org/core-lib` rather than defaulting to local origin repo.
+- Validates the issue identifier as numeric and extracts content safely.
 
-Setup: same fixture as S2, task adds: "While you are in there, main.ts
-should also log a timestamp."
+## S5 — Closed issue confirmation gate
+Setup: "Fix issue #15." The issue fetch returns `state: CLOSED`.
 
 Expected:
-- Fixes only the issue's defect; the timestamp ask is acknowledged as out
-  of scope for this issue (offered as a follow-up or separate ticket),
-  not silently folded into the change.
+- Detects the closed issue state immediately in Step 1.
+- Stops and warns the user that the issue is already closed; asks for explicit confirmation before writing any code.
+
+## Baseline failure modes to watch for (RED)
+- Re-deriving a root cause the issue already documents.
+- Changing code before demonstrating a reproducing test failure.
+- Silently widening scope beyond the ticket requirements.
+- Promising that `ship` will post an RCA comment or apply labels.
+- Committing or pushing from `fix-issue`.

package/skills/git/fix-issue/references/diagnosis-and-rca.md

@@ -0,0 +1,46 @@
+# Diagnosis, Why-Chains, and Root Cause Analysis (RCA)
+
+This reference outlines diagnosis techniques, why-chain construction, and root-cause documentation for `fix-issue`.
+
+## Diagnosing Unknown Causes
+
+When an issue does not already pinpoint the root cause:
+1. **Reproduce first**: Write a reproduction test script or minimal test case before altering any application logic. Run it and verify it fails with the expected symptom.
+2. **Trace the fault**: Follow the call stack or data flow backwards from the failure site to the originating trigger.
+3. **Construct a why-chain**:
+   ```
+   WHY <observed failure>?  -> because <immediate condition> (evidence: path/file.ts:123)
+   WHY <immediate condition>? -> because <underlying cause>   (evidence: path/file.ts:89)
+   ROOT CAUSE: <the exact defect to fix>                    (evidence: path/file.ts:45)
+   ```
+   Every link in the chain must cite a verified line of code or observed runtime state. A link without an observed citation remains an unverified hypothesis.
+
+## Routine Fixes vs Standalone RCA
+
+- **Routine fixes**: The why-chain is included directly in the final completion summary presented to the user. No separate RCA file is required.
+- **Complex or high-impact defects**: A standalone RCA document or detailed why-chain is written when:
+  - The defect caused data corruption, downtime, or security exposure.
+  - The diagnosis uncovered multiple interacting failure modes.
+  - The fix requires significant architectural changes or breaking behavioral adjustments.
+
+## RCA Destination and Issue Tracking
+
+- An RCA or diagnosis artifact stays in the local repository or task output during development.
+- **Do not assume downstream tools post comments automatically**: `ship` handles atomic commits and pull requests; it does not automatically post closing comments or attach labels to issues.
+- If the maintainer or repository workflow calls for recording the RCA on the tracker issue (for example, under an `rca` status label), format the comment clearly and request explicit user confirmation (`ask_user`) before running:
+  ```bash
+  gh issue comment <id> --repo <owner/repo> --body-file "$rca_file"
+  ```
+- If the repository uses an `rca` label, propose applying it only after the user approves:
+  ```bash
+  gh issue edit <id> --repo <owner/repo> --add-label "rca"
+  ```
+
+## Respecting Maintainer Constraints
+
+If an issue contains comments from maintainers specifying:
+- Non-negotiable interfaces or constraints
+- Performance budgets or dependencies that must not be added
+- Out-of-bounds files or packages
+
+These constraints are binding. If technical reality makes compliance impossible, stop, document the contradiction with evidence, and ask for user guidance before proceeding.