xtrm-tools 0.7.3 → 0.7.4

package/.xtrm/skills/default/xt-debugging/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: xt-debugging
+description: Complete debugging workflow — error analysis, log interpretation, performance profiling, and GitNexus call-chain tracing. Use when investigating bugs, errors, crashes, or performance issues.
+---
+
+# xt-debugging
+
+Systematic debugging using the GitNexus knowledge graph for call-chain tracing, combined with error analysis, log interpretation, and performance profiling.
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "This endpoint returns 500"
+- Investigating crashes, unexpected behavior, or regressions
+- Performance issues
+- Reading logs or stack traces
+
+---
+
+## Prerequisites
+
+GitNexus must be indexed before starting. If you see "index is stale" or no results:
+
+```bash
+npx gitnexus analyze   # re-index the repo (run this, then retry)
+npx gitnexus status    # verify freshness
+```
+
+---
+
+## Phase 1 — Triage
+
+Understand the symptom before touching any code.
+
+1. Read the full error message and stack trace
+2. Identify the suspect symbol (function, class, endpoint)
+3. Check for regressions — what changed recently?
+   ```
+   gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   ```
+
+---
+
+## Phase 2 — Knowledge Graph Investigation
+
+```
+1. gitnexus_query({query: "<error text or symptom>"})   → Related execution flows + symbols
+2. gitnexus_context({name: "<suspect>"})                → Callers, callees, process participation
+3. READ gitnexus://repo/{name}/process/{processName}    → Full step-by-step execution trace
+4. gitnexus_cypher({...})                               → Custom call chain if needed
+```
+
+### Patterns by Symptom
+
+| Symptom | Approach |
+|---------|----------|
+| Error message | `query` for error text → `context` on throw site |
+| Wrong return value | `context` on function → trace callees for data flow |
+| Intermittent failure | `context` → look for external calls, async deps, race conditions |
+| Performance issue | `context` → find hot-path symbols with many callers |
+| Recent regression | `detect_changes` to see what changed |
+
+### Example — "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external, no timeout)
+
+4. Root cause: fetchRates has no timeout → intermittent failures under load
+```
+
+---
+
+## Phase 3 — Root Cause Analysis
+
+1. **Reproduce** — Identify minimal reproduction steps
+2. **Trace data flow** — Follow the value/control flow from input to error
+3. **Isolate** — Narrow to the smallest failing unit
+4. **Hypothesize** — Form explicit hypothesis before reading more code
+5. **Confirm** — Verify hypothesis against source, not just symptoms
+
+Common root cause categories:
+- **Null/undefined** — missing guard, wrong assumption about data shape
+- **Race condition** — async ordering, missing await, shared mutable state
+- **External dependency** — timeout, API contract change, env difference
+- **Type mismatch** — serialization, casting, implicit coercion
+- **Configuration** — env var missing, wrong default, deployment drift
+
+---
+
+## Phase 4 — Log Analysis
+
+1. Read the full log output (not just the last line)
+2. Identify: timestamps, error levels, request IDs, correlation tokens
+3. Correlate events across log lines to build timeline
+4. Look for: first occurrence, frequency, affected subset, preceding events
+5. Summarize: what happened, when, why, and what was affected
+
+---
+
+## Phase 5 — Performance Profiling
+
+1. **Measure baseline** — Never optimize blind
+   ```bash
+   time <command>
+   ```
+2. **Profile** — Language-appropriate tools:
+   - Node.js: `--prof`, `clinic.js`, `0x`
+   - Python: `cProfile`, `py-spy`, `line_profiler`
+   - Go: `pprof`
+3. **Identify hotspot** — Usually 1–2 functions account for >80% of time; use `gitnexus_context` to confirm call frequency
+4. **Fix the bottleneck** — Minimal targeted change
+5. **Verify** — Measure again, compare against baseline
+
+---
+
+## Phase 6 — Remediation
+
+1. **Fix** — Minimal change that addresses the confirmed root cause
+2. **Verify** — Run the failing case to confirm fix
+3. **Regression test** — Add a test that would have caught this bug
+4. **Check blast radius** — `gitnexus_impact({target: "fixedSymbol", direction: "upstream"})`
+5. **Pre-commit scope check** — `gitnexus_detect_changes({scope: "staged"})`
+
+---
+
+## Checklist
+
+```
+- [ ] Read full error / stack trace
+- [ ] Identify suspect symbol
+- [ ] gitnexus_detect_changes to check for regressions
+- [ ] gitnexus_query for error text or symptom
+- [ ] gitnexus_context on suspect (callers, callees, processes)
+- [ ] Trace execution flow via process resource
+- [ ] Read source files to confirm root cause
+- [ ] Form explicit hypothesis before fixing
+- [ ] Verify fix against failing reproduction
+- [ ] Add regression test
+- [ ] gitnexus_detect_changes() before committing
+```

package/.xtrm/skills/default/xt-end/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: xt-end
+description: |
+  Autonomous session close flow for xt worktree sessions. Use this skill whenever
+  the user says "done", "finished", "wrap up", "close session", "ship it", "I'm done",
+  "ready to merge", or similar. Also activate when all beads issues in the session
+  are closed, or when the user explicitly runs /xt-end. This skill is designed for
+  headless/specialist use: it must make deterministic decisions, auto-remediate common
+  anomalies, and avoid clarification questions unless execution is truly blocked.
+---
+
+# xt-end — Autonomous Session Close Flow
+
+You are closing an `xt` worktree session. The canonical CLI is `xt end`, but you must normalize the session first and automatically handle common anomalies.
+
+## Operating Mode
+
+Default to **autonomous execution**:
+- do not ask the user routine clarification questions
+- prefer deterministic fallbacks over conversational review
+- only stop when a real blocker prevents safe progress
+- **always invoke `xt end --yes`** — never call `xt end` without this flag; the bare command prompts interactively for worktree removal which blocks autonomous execution
+
+## Success States
+
+Use these mental result classes while operating:
+- `SUCCESS_PR_CREATED`
+- `SUCCESS_PR_CREATED_WITH_WARNINGS`
+- `BLOCKED_UNCLOSED_SESSION_WORK`
+- `BLOCKED_NO_COMMITS`
+- `BLOCKED_AUTH`
+- `BLOCKED_CONFLICTS`
+- `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
+
+---
+
+## Stage 1 — Session Work Audit
+
+Run:
+```bash
+bd list --status=in_progress
+bd list --status=open
+git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline
+```
+
+Rules:
+- **Block** on `in_progress` issues
+- **Do not block** on unrelated open backlog issues
+- infer **session-touched issues** from commit messages and recent session work
+- if a touched issue is still not closed, close it if the work is complete; otherwise stop with `BLOCKED_UNCLOSED_SESSION_WORK`
+
+This skill is stricter about unfinished session work than about unrelated backlog.
+
+---
+
+## Stage 2 — Tree Normalization
+
+Run:
+```bash
+git status --short
+```
+
+If clean, continue.
+
+If dirty:
+- if the changes clearly belong to the just-finished session work, commit them automatically
+- if they look like unrelated WIP, stash them with a labeled stash message
+- never run `xt end` with a dirty tree
+
+Preferred automatic actions:
+```bash
+git add -A && git commit -m "<descriptive summary> (<issue-id>)"
+# or
+
+git stash push -m "xt-end:auto-stash before session close"
+```
+
+If changes cannot be classified safely, stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`.
+
+---
+
+## Stage 2.5 — Scope Verification
+
+Before committing or pushing, verify that branch changes match the expected scope of the session's closed issues. **Never skip this step** — unreviewed scope is the primary source of oversized or unintended PRs.
+
+Run:
+```bash
+git diff --stat origin/main..HEAD 2>/dev/null || git diff --stat $(git merge-base HEAD main)..HEAD
+```
+
+For each significantly changed symbol, check blast radius:
+```bash
+npx gitnexus impact <symbol-name>                   # upstream dependants — what else breaks
+npx gitnexus impact <symbol-name> -d downstream    # downstream dependencies
+```
+
+For Claude agents with MCP access, also run:
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+```
+
+**Rules:**
+- Changes clearly tied to session issues → continue
+- Files unrelated to session issues → classify as overscoped (handle in Stage 3D)
+- `npx gitnexus impact` returns HIGH or CRITICAL risk on a changed symbol → **stop and report to user** before continuing
+
+---
+
+## Stage 3 — Dry Run and Anomaly Detection
+
+Run:
+```bash
+xt end --dry-run
+```
+
+Parse the preview and check for anomalies:
+
+### A. Generic PR title
+Treat these as invalid:
+- `session changes`
+- `update`
+- `updates`
+- `misc`
+- `wip`
+- `work in progress`
+
+Auto-remediation:
+- prefer closed issue titles from this session
+- otherwise infer from changed files / dominant area
+- examples:
+  - `Add docs cross-check command and tests`
+  - `Integrate docs workflow with sync-docs`
+  - `Update docs workflow and CLI help`
+
+### B. Missing beads linkage
+If dry-run says no beads issues were found, but commit messages contain issue-like IDs, treat that as a tooling mismatch.
+
+Auto-remediation:
+- extract issue IDs directly from commit messages
+- continue with those IDs as manually inferred linkage
+- report the mismatch in the final summary
+
+### C. Generated artifacts in scope
+If files like `dist/` are included:
+- keep them if the repo conventionally commits built artifacts
+- otherwise revert them before continuing
+
+Use repository history/common practice as the heuristic; do not ask.
+
+### D. Overscoped PR
+Classify the PR scope into buckets:
+- source
+- tests
+- docs
+- skills
+- generated artifacts
+
+If all buckets support one coherent feature/change, continue.
+If they look unrelated, continue but mark the PR as `WITH_WARNINGS` and mention overscope in the final report.
+
+After auto-remediating anomalies, re-run:
+```bash
+xt end --dry-run
+```
+
+Repeat until the preview is acceptable or a hard blocker appears.
+
+---
+
+## Stage 4 — No-Commit / Session-Sanity Gate
+
+Before actual execution, ensure the branch really has changes:
+```bash
+git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null
+```
+
+If there are no commits ahead of base, stop with `BLOCKED_NO_COMMITS`.
+
+---
+
+## Stage 5 — Run xt end
+
+Run:
+```bash
+xt end --yes
+```
+
+Use non-interactive mode by default for autonomous execution.
+
+### If it succeeds
+Capture:
+- rebase success
+- push success
+- PR URL
+- linked issue count
+
+### If rebase conflicts occur
+Run:
+```bash
+git status
+```
+
+Resolve all conflict markers, then:
+```bash
+git add <resolved-files>
+git rebase --continue
+xt end --yes
+```
+
+If conflicts are too complex to resolve safely, stop with `BLOCKED_CONFLICTS`.
+
+### If push fails
+Try:
+```bash
+git fetch origin
+xt end --yes
+```
+
+### If `gh` auth fails
+Stop with `BLOCKED_AUTH` and report:
+```bash
+gh auth login
+```
+
+---
+
+## Stage 6 — Autonomous Cleanup
+
+Default behavior: **remove the worktree automatically** after a successful PR creation.
+
+Rationale:
+- branch is pushed
+- PR is open
+- worktree is disposable local state
+
+If cleanup is needed after `xt end --yes`:
+```bash
+git worktree remove <path> --force
+```
+
+Keep the worktree only if an explicit keep policy exists (for example, known immediate follow-up work on the same branch).
+
+---
+
+## Stage 7 — Final Report
+
+Always report:
+- final result class (`SUCCESS_PR_CREATED` or `SUCCESS_PR_CREATED_WITH_WARNINGS`)
+- PR URL
+- linked or inferred issues
+- whether anomalies were auto-remediated
+- whether the worktree was removed
+- reminder: monitor CI and merge when green; no auto-merge assumption
+
+If linkage had to be inferred from commits rather than detected by `xt end`, say so explicitly.
+
+---
+
+## Edge Cases
+
+**Already on main/master/default branch**
+- stop immediately; this is not an xt worktree session
+
+**No commits yet on branch**
+- stop with `BLOCKED_NO_COMMITS`
+
+**Dirty tree with unclear ownership**
+- stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
+
+**`gh` not authenticated**
+- stop with `BLOCKED_AUTH`
+
+**beads unavailable**
+- continue PR creation if possible
+- infer issues from commit messages when available
+- report linkage as unavailable/manual
+
+**Multiple anomalies at once**
+- remediate in order:
+  1. dirty tree
+  2. missing commits
+  3. generic title
+  4. missing issue linkage
+  5. generated artifacts
+  6. overscope warning
+
+## Policy Summary
+
+The autonomous rule is simple:
+- normalize the session
+- verify scope with gitnexus before committing
+- dry-run
+- auto-fix predictable anomalies
+- rerun dry-run
+- execute non-interactively
+- clean up automatically
+- stop only on genuine safety blockers