Kendex Issues

---
name: kendex-issues
description: "Load to monitor kendex's issue queue continuously or to run one fix cycle."
summary: "Watches open PRs, polls Linear, triages defects, and fixes them through orch. Consumers refresh through their own GitHub Actions workflow."
---

<!-- kendex:project-instructions:start -->
## Project Instructions

<!-- kendex:shared-instructions:start -->
Problems with a kendex-owned skill go through `kendex report`; check ownership in the file first.
<!-- kendex:shared-instructions:end -->
<!-- kendex:project-instructions:end -->

# kendex Issue Steward

watch → poll → triage → fix → merge → reschedule. One cycle per turn.

| Concern | Owning skill |
|---|---|
| Fix cycle (prepare → delegate → review → submit → merge) | **orch** |
| PR threads, replies, reviews, merges, CI logs | **github** |
| Watching open PRs | **review-gate** `pr-watch.sh` |
| Linear reads and writes | **linear** |

Hand-rolled PR mechanics (raw `gh api` where a `github.sh` command exists) are a defect.

## Loop (one turn)

1. **PR watch**: `GH_REPO=vanillagreencom/kendex .agents/skills/review-gate/scripts/pr-watch.sh`. Silence + exit 0 = nothing needs you. Attention lines → act through the github skill. After a gate-green, also check `isInMergeQueue` + `autoMergeRequest` (GraphQL). Queue ejection is silent: re-arm once; a second ejection is a flaky required suite. Quarantine, never re-arm loops.
2. **Poll Linear**: `linear.sh issues list --state "Triage,Backlog,Todo,In Progress" --max`. Linear is the complete queue (GitHub→Linear sync is one-way); Triage holds the GitHub-synced arrivals. Cross-check `gh issue list --repo vanillagreencom/kendex --state open`: an open GH issue whose Linear mirror is Done is residue, so close it naming the PR; one with no mirror means the sync broke, so triage it from GitHub and say so. Nothing on either surface → reschedule.
3. **Triage** each issue (below); run the fix cycle for each valid defect. Mutate on the issue's home surface: GH-mirrored issues (Linear body links the GH issue) are closed/commented on GitHub; Linear-native ones through the linear skill. PR body carries `Closes KEN-<n>` plus `Closes #<n>` when a mirror exists.
4. **Reschedule** (Cadence). Stop only if the user asked.

## Triage

- **Already fixed** → compare the marker's `source=<repo>@<commit7>` to the fix commit before investigating.
- **Duplicate** → close, name the canonical issue.
- **Not a kendex asset** → ownership is the asset's SKILL.md frontmatter (`source: kendex`), never its install path. Close with the reason; repost project-local items to the owning repo, cross-link, notify that repo's overseer (tmux window 1 of `memsira`, `drovr`, `hyprtrade`). Never fix a consuming repo's defect.
- **Edge case (<1% of users), contrived layout, race between two local processes, or reviewer hypothetical with no report** → cancel with the reason. The bar for a kendex issue is a reported symptom.
- **Over-built proposal** → cancel; state the simpler approach in one line if one exists.
- **Genuine kendex defect** (skills/, agents/, hooks/, pi-extensions/, crates/, ui/) → fix cycle.
- **Unfindable reference** → `git log -S '<name>' --all` first. A name that never existed is a typo: close with the evidence; never ship a shim.
- **Empty body** → ask for the concrete repro; leave open.

## Fix cycle: load orch

orch owns every step. kendex-specific parameters:

- **Delegate to**: follow `dev` § Implementer selection for maintenance, runtime and UI work; `iced` owns Iced views even under `crates/`. Tests required; relevant suite green (`bash skills/orch/tests/run-all.sh`, per-skill `tests/*.sh`, `cargo test --workspace`).
- **Scope is the reported symptom** (dev skill § Engineering Rules, plus its two exceptions: mechanical enablers ride, an armed defect is in scope). Expect the fix to be about the size of its first commit.
- **Fix direction**: determinism and tooling first, meaning a deletion, a short-circuit, or a script. Added prose last. Skills are instructions, not explanations; `tools/guard` refuses history and reasons in them.
- **Document size**: follow [doc-limits policy](../doc-limits/references/policy.md).
- **Review must converge** (orch SKILL.md): a recurring defect class is fixed at its source, never per comment. A round that is only scope, test-coverage, or wording asks ends the review: reply, resolve, push nothing, merge through the gate. Replies are `Fixed in <sha>`, `Declined: <reason>`, or `Tracked: KEN-<n>` (issue created first, since the gate rejects a tracking claim naming no issue). Never `--admin`.
- **Review the diff yourself** before submit, finding the actual root cause, not a plausible one. A stalled delegate: inspect its worktree, nudge once.
- Findings and coupled defects disposition per orch `references/finding-disposition.md`. The excluded classes come ahead of the defect fork, one reply form per thread.
- Disjoint files → parallel; same file → sequence or bundle.
- A required check that cannot be rerun gets a fresh head (`commit --amend --no-edit` + `push --force-with-lease`) only where the amend exception in [dev SKILL.md § Engineering Rules](../dev/SKILL.md#engineering-rules) permits it; never a merge past red.

## Consumer refresh

Consumers pull updates through their own GitHub Actions workflow. [Review-gate adoption](../review-gate/references/adoption.md) owns its setup and operation.

- File defects in rendered content upstream against kendex. Fix them through the fix cycle.
- Coordinate consumer manifest changes and workflow adoption with the consumer's overseer.

### This skill's home

Source: `.agents/skills/kendex-issues/SKILL.md` in the kendex checkout, the real directory, declared `source = "in-place"` and installed project-scoped only. `git rev-parse --show-toplevel` prints that checkout's root from anywhere inside it. Edit it there; the per-harness links already point at it, and an edit is the source changing, so `kendex refresh`, `kendex check` and `kendex verify` stay green with no apply, once the first refresh after upgrading kendex has re-recorded the entry. kendex writes one thing into the file, the project-instructions block between its markers; leave the markers in place. A `~/.agents/skills/kendex-issues` link is a collision. Delete it.

## Guardrails

- Never pipe a state-changing or guard command through `tail`/`head`/`grep` in a `&&` chain. Run bare, read the result, then trim. Read `worktree create`'s full output before entering it; an ownership refusal means another session owns the work.
- **Ownership.** Before a fix cycle, check for a remote branch, open PR, or foreign worktree for the issue. Active peer → hands off. A PR with unresolved threads and no pushes or replies for ~2 h whose session is idle is abandoned: take it over, answer every thread, note the takeover.
- **Consumer boundary.** Consumers own their refresh branches and pull requests. Coordinate other consumer changes with their overseer through [peer mail](../orch/references/peer-mail.md).
- **Branch safety.** Never switch or commit on a checkout mid-work; use a worktree off `origin/main`. Never `git stash` in a shared checkout.
- **Scoped commits, verified pushes.** Inspect diffs, `kendex verify`, confirm it landed.
- **Box load poisons suites.** A red suite under load: check uptime, rerun in isolation, A/B against clean HEAD.
- **Clean up** merged worktrees and stale branches; keep local and remote main in sync.

## Cadence

Widen toward ~60 min when quiet; tighten toward ~15–20 min after a new issue or a burst.