From 572e14b7d393851d0640039918389eac735b1dbe Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 00:09:14 +0000 Subject: [PATCH] Add /issues skill and outstanding-work memory ledger Introduce a durable, cross-session tracker for outstanding tasks, recommendations, and issues: - docs/outstanding-issues.md: the persistent memory (single source of truth), seeded from existing repo debts with source pointers. - .claude/skills/issues/SKILL.md: the /issues skill that reads the ledger back grouped by priority (read-only by default) and supports add/done/update/capture mutations that commit only the ledger. - AGENTS.md: a pointer so future sessions/tools discover the memory. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_018v3T5ahDyiT8nHqdjCdfB8 --- .claude/skills/issues/SKILL.md | 72 ++++++++++++++++++++++++++++++++++ AGENTS.md | 14 +++++++ docs/outstanding-issues.md | 48 +++++++++++++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 .claude/skills/issues/SKILL.md create mode 100644 docs/outstanding-issues.md diff --git a/.claude/skills/issues/SKILL.md b/.claude/skills/issues/SKILL.md new file mode 100644 index 000000000..228433931 --- /dev/null +++ b/.claude/skills/issues/SKILL.md @@ -0,0 +1,72 @@ +--- +name: issues +description: Track and recall all outstanding tasks, recommendations, and issues for this repo as durable cross-session memory. Use when the user types "/issues" (state the open items back), or asks to add/close/update/capture an outstanding task, recommendation, or issue. The memory lives in docs/outstanding-issues.md; a plain "/issues" is read-only. +--- + +# issues — the outstanding-work memory + +`docs/outstanding-issues.md` is the durable, cross-session memory of everything still outstanding: +open **tasks**, **recommendations** not yet acted on, and **issues** not yet resolved. Chat context +resets; that file does not. This skill reads it back and keeps it current. + +**The ledger is the source of truth, not chat memory.** Never answer `/issues` from conversation +recall — always read the file first, so the answer is correct even in a fresh session. + +## Trigger + +- User types `/issues` (optionally with a subcommand or filter below). +- User asks to add / close / update / list / capture an outstanding task, recommendation, or issue. + +## Default: `/issues` (read-only) + +1. Read `docs/outstanding-issues.md`. +2. State the **open items** back, grouped by priority (P1 → P3), each as + `#ID · type · summary — next action (source)`. +3. End with a one-line count, e.g. `5 open: 0×P1, 3×P2, 2×P3 · 0 resolved this session`. +4. Do **not** mutate the file or commit on a plain read. + +If a filter is given, narrow step 2: `/issues P1` (by priority), `/issues issues` / `/issues recs` +/ `/issues tasks` (by type), `/issues ` (summary/detail substring match). + +## Mutating subcommands + +Parse the intent from natural language too — the exact syntax is a convenience, not a requirement. + +- **`/issues add `** — append a row to **Open items**. Infer `Pri`/`Type` from the text + (ask only if genuinely ambiguous; default `P2`/`task`). Allocate the ID from the + `` marker, then bump that marker. Fill `Source` with + `session ` unless the user names one; `Added` is today's date. +- **`/issues done [outcome]`** — move that row from **Open items** to **Resolved / archive** + with today's date and a one-line outcome. Archive, never delete. +- **`/issues update `** — edit an open row's summary or next action in place. +- **`/issues capture`** — scan the current session for recommendations, follow-ups, deferrals, and + unfixed problems that surfaced but were not recorded. Propose them as a numbered list and add the + confirmed ones (dedupe against existing rows first — do not re-add something already tracked). + +## Capture discipline (proactive memory) + +When a task in _any_ session ends with unresolved follow-ups — a deferred fix, a "revisit when X" +recommendation, a known risk, a TODO you had to leave — offer to record them here before the context +is lost. That is what makes this a memory rather than a static list. Prefer one crisp row over a +paragraph; put the smallest next action in **Detail / next action**. + +## Writing rules + +- Keep the table format and column order exactly as in `docs/outstanding-issues.md`. One row per item. +- IDs are monotonic and never reused — always allocate from the `issues:next-id` marker and bump it. +- Escape `|` inside cell text (write `\|`) so the markdown table stays intact. +- Respect the repo's RAG/clinical/privacy flagging rules if an item _itself_ touches a protected + surface — recording it here is fine, but acting on it later still needs the usual gate. + +## Persist the memory (commit) + +After any mutation, stage and commit **only** `docs/outstanding-issues.md` so the memory survives the +ephemeral container and other worktrees: + +``` +git add docs/outstanding-issues.md +git commit -m "issues: " +``` + +Do not stage or commit anything else, and do not push unless the user asks (or you are already in a +handoff/upload flow). A plain read-only `/issues` commits nothing. diff --git a/AGENTS.md b/AGENTS.md index baf21a7c2..bc8c6e90a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -411,6 +411,20 @@ Run the matching planner command in `docs/productivity-workflows.md` without sid +## Outstanding-work memory (`/issues`) + +`docs/outstanding-issues.md` is the durable, cross-session memory of every outstanding **task**, +**recommendation**, and **issue** for this repo. Chat context resets between sessions; that file does +not, so anything worth remembering after a session ends belongs there. + +- When the user types `/issues`, invoke the `issues` skill (`.claude/skills/issues/SKILL.md`): read + `docs/outstanding-issues.md` and state the open items back, grouped by priority. A plain `/issues` + is read-only — it mutates and commits nothing. +- `/issues add|done|update|capture …` mutate the ledger; each mutation commits **only** + `docs/outstanding-issues.md` (no push unless the user asks or you are already handing off). +- Proactively offer to `capture` unresolved follow-ups, deferrals, and known risks into the ledger + before a session's context is lost — that is what keeps it a memory rather than a stale list. + ## Codex GitHub review behavior These instructions apply to Codex GitHub pull request reviews and Codex tasks started from PR comments. diff --git a/docs/outstanding-issues.md b/docs/outstanding-issues.md new file mode 100644 index 000000000..38620f445 --- /dev/null +++ b/docs/outstanding-issues.md @@ -0,0 +1,48 @@ +# Outstanding Issues, Recommendations & Tasks + +Durable, cross-session memory of everything still outstanding for this repo: open **tasks**, +**recommendations** not yet acted on, and **issues** not yet resolved. Chat context is ephemeral +(sessions summarise and reset); this file is not — it is the single source of truth the +[`/issues` skill](../.claude/skills/issues/SKILL.md) reads back and updates. + +**Rule of thumb:** if it is worth remembering after this session ends, it belongs here. + +## How this is used + +- Say `/issues` in Claude Code → the skill reads this file and states the open items back, + grouped by priority with a one-line summary count. Nothing is mutated on a plain read. +- `/issues add …`, `/issues done `, `/issues capture`, and friends mutate the tables below. + The full command surface lives in the skill file. +- Every mutation keeps this file committed so the memory survives across sessions and worktrees. + +## Conventions + +- **ID** is a monotonic `#NNN`, never reused. Allocate the next number above the current max + across _both_ tables (open + resolved). +- **Pri**: `P1` (do next / blocking), `P2` (should do), `P3` (nice-to-have / revisit-when). +- **Type**: `task` (a concrete unit of work), `rec` (a recommendation to weigh), or + `issue` (a defect / risk / gap). +- **Detail / next action** is the smallest thing that would move the item forward. +- **Source** points at where it came from: a doc, a PR (`#123`), a file:line, or `session YYYY-MM-DD`. +- Resolving an item moves its row to **Resolved / archive** with the date and a one-line outcome — + rows are archived, not deleted, so the history stays auditable. + + + +## Open items + +| ID | Pri | Type | Summary | Detail / next action | Source | Added | +| ---- | --- | ---- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------- | +| #001 | P2 | task | Semantic reranking still gated off | `RAG_SEMANTIC_RERANK_ENABLED=false` from PR #901. Do not enable until the provider-backed 36/36 retrieval-quality gate **and** an ambiguity-focused canary are explicitly approved and recorded. | `docs/process-hardening.md` (Semantic reranking rollout debt); PR #901 | 2026-07-21 | +| #002 | P2 | task | Process-ownership fix not yet isolated on `main` | `scripts/run-eval-safe.mjs` still terminates residual repo processes broadly. Isolate the child-owned `terminateOwnedProcessTree(child.pid)` approach + the regression test proving unrelated Vitest/Playwright/Next processes survive; verify statically — do **not** start a provider-backed eval. | `docs/process-hardening.md` (High-priority local process ownership) | 2026-07-21 | +| #003 | P2 | task | Staging tenancy release evidence outstanding | The provider-backed A/B tenancy regression is intentionally outside local + PR gates. Run the standalone manual/nightly workflow and attach a recent green evidence artifact **before release**. | `docs/process-hardening.md`; `docs/staging-tenancy-release-evidence.md` | 2026-07-21 | +| #004 | P3 | rec | Rescope provider-gated RAG safety ideas | If explicitly approved, rescope only the still-relevant preflight utilities/tests (answer-quality thresholds, cost-cap preflight, deep-health) against current `main`; keep live OpenAI/Supabase validation separate. Do **not** replay the stale 754-line retrieval migration/worktree wholesale. | `docs/process-hardening.md` (Provider-gated RAG safety ideas) | 2026-07-21 | +| #005 | P3 | rec | `finalScore` saturates at clamp ceiling | Base + ~40 stacked boosts routinely exceed 1.0, so strong matches tie at 1.0 and order by an arbitrary `document_id` tiebreak. If ranking is ever revisited, break ties by the **pre-clamp** score rather than raising the `[0,1]` ceiling (downstream gates assume `[0,1]`). Not a defect on the current golden set. | `docs/rag-hybrid-findings-and-todo.md` P1 item 4; `src/lib/rag/clinical-search.ts:1362` | 2026-07-21 | + +## Resolved / archive + +Move resolved rows here with the resolution date and a one-line outcome. Keep them — do not delete. + +| ID | Type | Summary | Outcome | Resolved | +| ------------ | ---- | ------- | ------- | -------- | +| _(none yet)_ | | | | |