ldraney/claude-custom

Fork 0

Scope review pipeline: jidoka for the left side of the board #161

New issue

Closed

opened 2026-03-26 03:46:55 +00:00 by forgejo_admin · 3 comments

forgejo_admin commented

2026-03-26 03:46:55 +00:00

Contributor

Type

Feature

Lineage

standalone — discovered when Betty Sue forgot to invoke /review-ticket on forgejo_admin/dotfiles#1, exposing that the scoping pipeline has zero enforcement

Repo

forgejo_admin/claude-custom

User Story

As the platform operator
I want the scoping pipeline (backlog→next_up) to have the same hook-enforced rigor as the execution pipeline (in_progress→done)
So that poorly scoped tickets never reach dev agents, preventing rework waste

Context

The execution pipeline has 4 hooks enforcing quality gates (label-on-branch, label-on-pr, label-on-verdict, remind-sprint-update). The scoping pipeline has zero. This creates three failure modes:

No enforcement on scope review — Betty Sue must remember to invoke /review-ticket. She forgot on dotfiles#1. There's no hook blocking todo→next_up without a passing review.
Fragmented specs — when /review-ticket returns NEEDS_REFINEMENT, scope expansions go as Forgejo comments instead of updating the issue body. Dev agent reads the original body and misses critical scope changes (see GroupMe #160 example where scope grew from 1 tool to 4).
No review-fix loop — the /review-ticket skill is fire-and-forget. There's no convention for fix→re-review→fix→re-review until APPROVED, unlike the PR review-fix loop.

This is the TPS "second pillar" problem: we have jidoka for code (QA hooks) but not for scope (ticket review hooks). Toyota's system only worked because both pillars were enforced — JIT made problems visible, jidoka provided the mechanism to solve them immediately. Our scoping pipeline has no jidoka.

File Targets

Files to create:

~/.claude/hooks/check-board-advance.sh — hook blocking todo→next_up without passing review
pal-e-docs note sop-ticket-scope-review — SOP documenting the review-fix-re-review cycle

Files to modify:

~/.claude/skills/review-ticket/SKILL.md — add fix-and-re-review loop logic (also update skill-review-ticket agent workflow note in pal-e-docs)
~/.claude/settings.json or ~/.claude/settings.local.json — register the new hook
pal-e-docs note template-ticket — add Review Gate section
pal-e-docs note sop-board-workflow — reference new SOP in related section

Files NOT to touch:

Execution pipeline hooks (label-on-branch, label-on-pr, label-on-verdict) — those work fine
/review-pr skill — code review is a separate concern

Acceptance Criteria

Hook blocks update_board_item when column changes todo→next_up without a passing review note for that item
Hook also covers bulk_move_board_items — this tool can advance items todo→next_up and would bypass an update_board_item-only hook
Hook does NOT fire during sync_board operations or automated board syncs (e.g. session-start-board-sync.sh) — only on explicit user-driven column advances
/review-ticket skill handles the fix-and-re-review loop: NEEDS_REFINEMENT → fix body → re-review → loop until APPROVED
Convention documented: refinements UPDATE issue body (consolidated spec), comments document history (why scope changed)
SOP note sop-ticket-scope-review exists, tagged sop,active
template-ticket documents the review gate
End-to-end: create ticket → review → NEEDS_REFINEMENT → fix body → re-review → APPROVED → advance to next_up succeeds
End-to-end: attempt to advance todo→next_up without review → hook blocks with helpful message

Test Expectations

Manual test: create a board item in todo, attempt to move to next_up without review → blocked
Manual test: run /review-ticket, get APPROVED, move to next_up → succeeds
Manual test: run /review-ticket, get NEEDS_REFINEMENT, update issue body, re-review → APPROVED → advance
Run command: manual testing via Claude Code session (hooks are shell scripts, not unit-testable in isolation)

Constraints

Hook must check for review notes via pal-e-docs API or tool_input inspection (resolved: curl-to-API approach)
check-board-item.sh does NOT query pal-e-docs API — it only validates tool_input fields via jq. The new hook introduces a novel pattern if it needs runtime API calls.
Review note naming convention must be consistent so the hook can find them (current: review-{item_id}-{date})
The consolidated spec convention means the issue body is the SINGLE source of truth for dev agents — no reading comments
AC5 (consolidated spec) requires programmatic issue body updates. mcp__forgejo__update_issue now exists. If unavailable at dev time, curl fallback via Forgejo REST API.
Must not break existing board operations (backlog→todo, in_progress→qa, etc.)

Resolved: curl-to-API approach. Ground truth from the database is more reliable than tool_input inspection. Accept the runtime dependency on pal-e-docs API availability.

Decomposition Recommendation

Review review-364-2026-03-27 flagged this as too large for a single agent pass (7 AC, 2 systems, ~15-20 min). Recommend splitting into 3 tickets via template-board:

Hook + settings — check-board-advance.sh, settings.json registration, bulk_move coverage, sync_board exclusion (AC 1-3, 8-9)
Skill rewrite + SOP — /review-ticket SKILL.md loop logic, sop-ticket-scope-review note, consolidated spec convention (AC 4-6)
Doc updates — template-ticket review gate section, sop-board-workflow cross-reference, skill-review-ticket note update (AC 7)

Do NOT advance to next_up until decomposed and arch decision resolved.

Checklist

PR opened
Tests pass
No unrelated changes

sop-board-workflow — column semantics this extends
pr-review-loop — the code-side mirror of this scope-side gate
template-ticket — ticket structure this adds a gate to
skill-review-ticket — skill note the /review-ticket skill reads
forgejo_admin/dotfiles#1 — the ticket that exposed the gap
forgejo_admin/claude-custom#160 — GroupMe ticket where fragmented spec problem was discovered

### Type Feature ### Lineage standalone — discovered when Betty Sue forgot to invoke /review-ticket on forgejo_admin/dotfiles#1, exposing that the scoping pipeline has zero enforcement ### Repo `forgejo_admin/claude-custom` ### User Story As the platform operator I want the scoping pipeline (backlog→next_up) to have the same hook-enforced rigor as the execution pipeline (in_progress→done) So that poorly scoped tickets never reach dev agents, preventing rework waste ### Context The execution pipeline has 4 hooks enforcing quality gates (label-on-branch, label-on-pr, label-on-verdict, remind-sprint-update). The scoping pipeline has zero. This creates three failure modes: 1. **No enforcement on scope review** — Betty Sue must *remember* to invoke /review-ticket. She forgot on dotfiles#1. There's no hook blocking todo→next_up without a passing review. 2. **Fragmented specs** — when /review-ticket returns NEEDS_REFINEMENT, scope expansions go as Forgejo comments instead of updating the issue body. Dev agent reads the original body and misses critical scope changes (see GroupMe #160 example where scope grew from 1 tool to 4). 3. **No review-fix loop** — the /review-ticket skill is fire-and-forget. There's no convention for fix→re-review→fix→re-review until APPROVED, unlike the PR review-fix loop. This is the TPS "second pillar" problem: we have jidoka for code (QA hooks) but not for scope (ticket review hooks). Toyota's system only worked because both pillars were enforced — JIT made problems visible, jidoka provided the mechanism to solve them immediately. Our scoping pipeline has no jidoka. ### File Targets Files to create: - `~/.claude/hooks/check-board-advance.sh` — hook blocking todo→next_up without passing review - pal-e-docs note `sop-ticket-scope-review` — SOP documenting the review-fix-re-review cycle Files to modify: - `~/.claude/skills/review-ticket/SKILL.md` — add fix-and-re-review loop logic (also update `skill-review-ticket` agent workflow note in pal-e-docs) - `~/.claude/settings.json` or `~/.claude/settings.local.json` — register the new hook - pal-e-docs note `template-ticket` — add Review Gate section - pal-e-docs note `sop-board-workflow` — reference new SOP in related section Files NOT to touch: - Execution pipeline hooks (label-on-branch, label-on-pr, label-on-verdict) — those work fine - `/review-pr` skill — code review is a separate concern ### Acceptance Criteria - [ ] Hook blocks `update_board_item` when column changes todo→next_up without a passing review note for that item - [ ] Hook also covers `bulk_move_board_items` — this tool can advance items todo→next_up and would bypass an `update_board_item`-only hook - [ ] Hook does NOT fire during `sync_board` operations or automated board syncs (e.g. `session-start-board-sync.sh`) — only on explicit user-driven column advances - [ ] `/review-ticket` skill handles the fix-and-re-review loop: NEEDS_REFINEMENT → fix body → re-review → loop until APPROVED - [ ] Convention documented: refinements UPDATE issue body (consolidated spec), comments document history (why scope changed) - [ ] SOP note `sop-ticket-scope-review` exists, tagged sop,active - [ ] `template-ticket` documents the review gate - [ ] End-to-end: create ticket → review → NEEDS_REFINEMENT → fix body → re-review → APPROVED → advance to next_up succeeds - [ ] End-to-end: attempt to advance todo→next_up without review → hook blocks with helpful message ### Test Expectations - [ ] Manual test: create a board item in todo, attempt to move to next_up without review → blocked - [ ] Manual test: run /review-ticket, get APPROVED, move to next_up → succeeds - [ ] Manual test: run /review-ticket, get NEEDS_REFINEMENT, update issue body, re-review → APPROVED → advance - Run command: manual testing via Claude Code session (hooks are shell scripts, not unit-testable in isolation) ### Constraints - Hook must check for review notes via pal-e-docs API or tool_input inspection (resolved: curl-to-API approach) - `check-board-item.sh` does NOT query pal-e-docs API — it only validates tool_input fields via jq. The new hook introduces a novel pattern if it needs runtime API calls. - Review note naming convention must be consistent so the hook can find them (current: `review-{item_id}-{date}`) - The consolidated spec convention means the issue body is the SINGLE source of truth for dev agents — no reading comments - AC5 (consolidated spec) requires programmatic issue body updates. `mcp__forgejo__update_issue` now exists. If unavailable at dev time, curl fallback via Forgejo REST API. - Must not break existing board operations (backlog→todo, in_progress→qa, etc.) **Resolved:** curl-to-API approach. Ground truth from the database is more reliable than tool_input inspection. Accept the runtime dependency on pal-e-docs API availability. ### Decomposition Recommendation Review `review-364-2026-03-27` flagged this as too large for a single agent pass (7 AC, 2 systems, ~15-20 min). Recommend splitting into 3 tickets via template-board: 1. **Hook + settings** — `check-board-advance.sh`, settings.json registration, `bulk_move` coverage, `sync_board` exclusion (AC 1-3, 8-9) 2. **Skill rewrite + SOP** — `/review-ticket` SKILL.md loop logic, `sop-ticket-scope-review` note, consolidated spec convention (AC 4-6) 3. **Doc updates** — `template-ticket` review gate section, `sop-board-workflow` cross-reference, `skill-review-ticket` note update (AC 7) Do NOT advance to next_up until decomposed and arch decision resolved. ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `sop-board-workflow` — column semantics this extends - `pr-review-loop` — the code-side mirror of this scope-side gate - `template-ticket` — ticket structure this adds a gate to - `skill-review-ticket` — skill note the /review-ticket skill reads - `forgejo_admin/dotfiles#1` — the ticket that exposed the gap - `forgejo_admin/claude-custom#160` — GroupMe ticket where fragmented spec problem was discovered

forgejo_admin commented

2026-03-27 21:06:53 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-364-2026-03-27

Well-scoped issue with complete template, full traceability, and verified file targets -- but too large for a single agent pass.

Issues found:

Needs decomposition -- 6+ file targets across 2 systems, 7 acceptance criteria, 3 distinct concerns (hook, skill enhancement, docs). Recommend splitting into 3 tickets.
Undocumented dependency on #162 (Forgejo MCP: add update_issue tool) -- the consolidated spec convention (criterion #3) requires programmatic issue body updates, but no update_issue MCP tool exists yet.
File path typo -- skill.md should be SKILL.md (uppercase). Also clarify that both the router (SKILL.md) and the agent workflow note (skill-review-ticket) need updates.
Blast radius gap -- hook on update_board_item must not fire during sync_board operations or it will block automated board syncs.

Recommend decomposition via template-board.

## Scope Review: NEEDS_REFINEMENT Review note: `review-364-2026-03-27` Well-scoped issue with complete template, full traceability, and verified file targets -- but too large for a single agent pass. **Issues found:** - **Needs decomposition** -- 6+ file targets across 2 systems, 7 acceptance criteria, 3 distinct concerns (hook, skill enhancement, docs). Recommend splitting into 3 tickets. - **Undocumented dependency on #162** (Forgejo MCP: add update_issue tool) -- the consolidated spec convention (criterion #3) requires programmatic issue body updates, but no `update_issue` MCP tool exists yet. - **File path typo** -- `skill.md` should be `SKILL.md` (uppercase). Also clarify that both the router (SKILL.md) and the agent workflow note (`skill-review-ticket`) need updates. - **Blast radius gap** -- hook on `update_board_item` must not fire during `sync_board` operations or it will block automated board syncs. Recommend decomposition via template-board.

forgejo_admin commented

2026-03-28 05:43:16 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-364-2026-03-27

Well-scoped ticket with complete template, full traceability, and strong context. However, it exceeds the 5-minute rule and has several issues requiring refinement before dev dispatch.

Issues found:

[DECOMPOSE] 7 AC across 2 systems (filesystem + pal-e-docs API), estimated 15-20 min. Split into 3 tickets via template-board: (1) hook + settings, (2) skill rewrite + SOP, (3) doc updates.
[BODY] File path case mismatch: skill.md should be SKILL.md (uppercase).
[BODY] False constraint: "follow pattern from existing check-board-item.sh" -- that hook does NOT query pal-e-docs API, it only validates tool_input fields. The new hook introduces a novel pattern (shell-to-API calls).
[BODY] Missing from scope: bulk_move_board_items can bypass the update_board_item hook to advance todo->next_up. Either hook both tools or document as known bypass.
[BODY] Missing blast radius note: sync_board and session-start-board-sync.sh could trigger column changes -- hook must not fire during sync operations.
[BODY] Undocumented dependency: AC3 (consolidated spec convention) requires programmatic issue body updates. No update_issue MCP tool exists -- document curl fallback.
[SCOPE] Architecture decision needed: should the hook query pal-e-docs via curl (new runtime dependency) or inspect tool_input for a pre-set review flag?

Recommend decomposition via template-board before advancing to next_up.

## Scope Review: NEEDS_REFINEMENT Review note: `review-364-2026-03-27` Well-scoped ticket with complete template, full traceability, and strong context. However, it exceeds the 5-minute rule and has several issues requiring refinement before dev dispatch. **Issues found:** - **[DECOMPOSE]** 7 AC across 2 systems (filesystem + pal-e-docs API), estimated 15-20 min. Split into 3 tickets via template-board: (1) hook + settings, (2) skill rewrite + SOP, (3) doc updates. - **[BODY]** File path case mismatch: `skill.md` should be `SKILL.md` (uppercase). - **[BODY]** False constraint: "follow pattern from existing check-board-item.sh" -- that hook does NOT query pal-e-docs API, it only validates tool_input fields. The new hook introduces a novel pattern (shell-to-API calls). - **[BODY]** Missing from scope: `bulk_move_board_items` can bypass the `update_board_item` hook to advance todo->next_up. Either hook both tools or document as known bypass. - **[BODY]** Missing blast radius note: `sync_board` and `session-start-board-sync.sh` could trigger column changes -- hook must not fire during sync operations. - **[BODY]** Undocumented dependency: AC3 (consolidated spec convention) requires programmatic issue body updates. No `update_issue` MCP tool exists -- document curl fallback. - **[SCOPE]** Architecture decision needed: should the hook query pal-e-docs via curl (new runtime dependency) or inspect tool_input for a pre-set review flag? Recommend decomposition via template-board before advancing to next_up.

forgejo_admin commented

2026-03-28 11:41:44 +00:00

Author

Contributor

Scope Review: READY

Review note: review-364-2026-03-27-v2

Re-review after refinement. All 7 recommendations from prior review addressed:

[BODY] x5 -- SKILL.md casing fixed, false constraint corrected, bulk_move added as AC2, sync_board exclusion added as AC3, update_issue dependency documented (tool confirmed available)
[SCOPE] x1 -- curl-to-API architectural decision resolved and documented in Constraints
[DECOMPOSE] x1 -- 3-ticket split documented in body with AC-to-ticket mapping

Scope is solid. Next step: create the 3 child tickets from the Decomposition Recommendation section, then dispatch.

## Scope Review: READY Review note: `review-364-2026-03-27-v2` Re-review after refinement. All 7 recommendations from prior review addressed: - **[BODY] x5** -- SKILL.md casing fixed, false constraint corrected, bulk_move added as AC2, sync_board exclusion added as AC3, update_issue dependency documented (tool confirmed available) - **[SCOPE] x1** -- curl-to-API architectural decision resolved and documented in Constraints - **[DECOMPOSE] x1** -- 3-ticket split documented in body with AC-to-ticket mapping Scope is solid. Next step: create the 3 child tickets from the Decomposition Recommendation section, then dispatch.