the01geek/prflow/retrospective-weekly

/prflow:retrospective-weekly — Weekly Orchestrator

This skill is the single entry point the maintainer invokes once a week (or on demand). It is a conductor: it runs deterministic bash/jq scripts from lib/ at every mechanical step and dispatches LLM subagents only at the two genuine-judgment points — per-PR retrospective analysis (Stage A) and per-pattern issue-spec drafting (Stage B). The loop proposes, it does not dispose: each actionable pattern is filed as one GitHub issue for the normal implement → review pipeline, not landed as an autonomous PR.

Subagent dispatch is user-requested here (injection-condition clause). Invoking /prflow:retrospective-weekly is the user's request for subagent dispatch at this loop's two judgment points — the Stage A per-PR retrospective subagents (Step 4) and the Stage B per-pattern issue-spec subagents (Step 8b) — thereby satisfying any injected "do not call the AgentTool unless the user requested it" condition there and nowhere else; every other step stays the deterministic scripts the conductor runs directly.

Helper-path form (textual). Every bundled-helper command in this skill is written inline with the full portable anchor — "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/<name> for a scripts/ helper and .../../lib/<name> for a lib/ helper — resolved per the Portable helper anchor note below. Never capture the anchor into a shell variable that a later statement reads: each Bash call is a fresh shell. The retrospective libraries are not sourced into this skill's shell; their cloud-used functions are reached through the retro-helper.sh <subcommand> dispatcher, invoked as a bare granted path (vendored literal first, portable-anchor fallback for the local tier), which reads its inputs from and writes its outputs to fixed .prflow/tmp/retro-helper/… files. retro-outcome-record.py calls are vendored-literal only, || true: only the workflow creates the record they write, and it guarantees that path.

Working-directory contract. This skill's lib//scripts/ helper paths are repo-relative literals resolving against the repository root; no fence emits a leading cd.

Every jq in this skill is invoked through the execution-verified wrapper "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/run-jq.sh (the scripts/ dir beside lib/), never bare jq — a shim-shadowed Windows/WSL host otherwise resolves an unrunnable jq. DEVFLOW_JQ is not exported to agent shells, so invoke the wrapper by path.

All scratch files live under .prflow/tmp/ (gitignored). The learnings store lives on the telemetry branch; a run works on an untracked copy under .prflow/learnings/, loaded in Step 1 and saved in Steps 7 and 9. No run opens a pull request.

Writing standard (any text you compose that lands on a GitHub surface — issue titles, the report, body content you assemble). Before composing such text, read the shared writing standard "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../lib/writing-standard.md and follow it. A failed load emits a breadcrumb naming the file and the failure kind, and you compose without it.

GitHub autolink hygiene (any text you compose that lands on a GitHub surface — issue titles, the report, body content you assemble): never put a bare # immediately before a number unless it is a real issue or PR reference — GitHub renders #2 as a link to issue/PR 2, which misleads readers. For an ordinal, count, or list position, spell it out ("item 2", "step 3"), never #2. Genuine references like #123 stay as-is. <!-- pruned-path-ok: illustrative autolink examples, not citations -->

Portable helper anchor (single-statement). The bundled-helper commands in this skill spell the skill directory as ${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}. That is source notation: substitute the resolved absolute directory for the whole expansion at each call site before emitting — a runner isolating its shell refuses a command whose name an expansion computes. Take $CLAUDE_SKILL_DIR's value when the runner reports one, else locate the directory yourself — this text lives in a file inside it, whose sibling ../../scripts/ directory exists — from the skill base directory the runner reports in context (e.g. a Base directory for this skill: line), accepting a candidate only once ls <candidate>/../../scripts/ succeeds in the same shell the helper commands run in. If a path form is rejected, use the form that shell reports (pwd shows it); a Windows-form base directory (C:\...) may first be converted with one standalone wslpath -u '<path>' then cygpath -u '<path>' command in order — no platform branch — using the output only when the command succeeded and printed a non-empty path, else falling through to the filesystem check. Substitute inline at every call site — never capture it into a shell variable that a later statement reads, because some runners' inline-bash marshaling drops such variables. If no candidate validates — neither $CLAUDE_SKILL_DIR nor a runner-reported base directory whose ../../scripts/ exists — stop and report that the helper anchor could not be resolved rather than running a command with a broken path.

Consumer prompt extension (load first). Before doing this skill's work, load any consumer-supplied prompt extension for this skill and honor it. From the repo root, run:

"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/load-prompt-extension.sh retrospective-weekly

If the invocation fails because the helper path does not exist (No such file, exit 127, or the platform equivalent), that is the anchor failure above: fix the anchor; do not report a missing extension. Otherwise, if the helper exits non-zero, a consumer extension exists but could not be loaded — surface its stderr message and do not silently proceed as if none existed. No PROMPT-EXTENSION-STATUS: line on stderr, as after a refusal, is an unestablished extension to report, never an empty one. If it exits 0 and prints text, treat that text as additional instructions appended to the end of this skill's own prompt for this run. If it exits 0 and prints nothing, proceed unchanged.

Procedure

Step 1 — Preflight

Confirm the working tree is clean outside the learnings working copy:

git status --porcelain -- . ':(exclude).prflow/learnings'

If the output is non-empty, stop and tell the user to stash or commit their changes before running the loop.

Confirm gh is authenticated:

gh auth status

If it fails, tell the user to run gh auth login and stop.

Confirm you are on main:

git branch --show-current

If not on main, run git checkout main.

Prepare the scratch directory. This also removes prior-run scratch, so a run can never read another run's stale bundle, output, or overrides snapshot:

mkdir -p .prflow/tmp
rm -f .prflow/tmp/new-entries.jsonl
# Remove prior-run scratch with `find … -delete`, not a bare `rm -f <glob>` (which
# aborts under zsh's nomatch and leaves every pattern uncleaned). Name here every file
# a later step reads back by path: readers guard input by readability alone, so a
# surviving readable copy renders the report from stale state.
find .prflow/tmp -maxdepth 1 -type f \( -name 'result-*.json' -o -name 'pr-*.context.json' -o -name 'overrides-prefiling.json' -o -name 'patterns.json' -o -name 'patterns-full.json' -o -name 'patterns.stderr' \) -delete 2>/dev/null
# Clear the depth-2 wrapper output dir too: those outputs are read back by path, some
# without gating on the wrapper's exit, so a surviving stale copy would fail open.
rm -rf .prflow/tmp/retro-helper 2>/dev/null || true
# Never wipe .prflow/tmp/retro-outcome/ or scan.json: the workflow's finalizer reads them.

Load the learnings store from a fresh fetch of the telemetry branch into .prflow/learnings/:

.prflow/vendor/prflow/scripts/retro-helper.sh learnings-hydrate || { ! test -x .prflow/vendor/prflow/scripts/retro-helper.sh && "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/retro-helper.sh learnings-hydrate; }

On a non-zero exit the store could not be loaded safely: stop and report its ::error:: line. Its outcome is in .prflow/tmp/retro-helper/learnings-hydrate-out.txt; a first-run: line is a normal start.

Step 2 — Scan

Fetch the list of unprocessed watched-author PRs merged in the last 7 days:

"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../lib/scan.sh > .prflow/tmp/scan.json

Ad-hoc / backfill / test runs. To run the loop against a specific set of PRs instead of the rolling 7-day window — e.g. backfilling old PRs, re-running after a fix, or testing the pipeline — pass --prs:

"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../lib/scan.sh --prs 774,786,772,789 > .prflow/tmp/scan.json

--prs skips the GitHub search and the already-processed filter (you named the PRs, so the loop trusts you), but still drops any number that isn't a merged retrospected branch. Everything downstream (Steps 3–10) is identical. Do not use --prs for the scheduled weekly run.

Each scan record carries repo (the <owner>/<name> the numbers were issued in) and pr_key (<owner>/<name>#<number>) beside number. The already-processed filter keys on pr_key, so a number already retrospected in one repository never suppresses the same number in another.

scan.sh writes to stdout and exits non-zero on unrecoverable errors. It exits non-zero when the repository cannot be resolved — an unresolved repository would make the processed set unqualified, and every stored number would then be read against whichever repository the run happens to be in. If the output array is empty:

"${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/run-jq.sh 'length == 0' .prflow/tmp/scan.json

→ true: report "Nothing to process — no unprocessed watched-author PRs in the last 7 days." and STOP.

Step 3 — Per-PR context fetch + cheap gate

Initialize counters:

prs_scanned=0
clean_count=0
analyzed_count=0
skipped_count=0     # mechanically- and Stage-A-skipped PRs
skip_records=()     # one-line report records, one per skip (never silent)
needs_analysis=()   # array of bundle paths

For each record in scan.json (iterate via "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/run-jq.sh -r '.[] | "\(.repo) \(.number)"'):

repo=<the record's repo>
number=<the pr number>
CTX=$("${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../lib/fetch-pr-context.sh "$number" --repo "$repo")

Increment prs_scanned.

Pass --repo rather than letting the fetcher resolve the current repository: a number is only meaningful beside the repository that issued it, and fetching the same number from the wrong one silently retrospects different work.

fetch-pr-context.sh writes the bundle to .prflow/tmp/pr-<owner>-<name>-<n>.context.json — the name carries the repository so two repositories' same-numbered PRs cannot overwrite each other — and echoes that file path to stdout, so $CTX is the path, not the bundle content.

Run the cheap gate against the bundle content:

GATE=$("${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../scripts/run-jq.sh -c -f "${CLAUDE_SKILL_DIR:-<absolute skill base directory this runner reports in context>}"/../../lib/cheap-gate.jq < "$CTX")

Outputs {"clean": <bool>, "reason": "<string>"}.

If clean == true: