Session Triage - Ship-End Research Routing

Scope: current conversation, gblock-party repo, $ship-end next-step routing. Date: 2026-06-03.

Verification verdict: verified Responsible gap: next-step routing contract

Summary

User-identified issue: The next-step routing for $ship-end should better detect research/alignment approval as a research workflow continuation, instead of treating it like an implementation-time manual step that needs the user to run a guided walkthrough.

Agent-verified issue: Verified. In the prior $ship-end report, I recommended $pack install guided-walkthrough even though the next work in tasks/todo.md was review of a Strategic Canvas alignment page and approval/feedback YAML for a research artifact. The positioning and strategic-canvas contracts explicitly treat this as a report-first research approval gate.

Impact: The recommendation could send the user into an unnecessary manual-work pack and obscure the actual continuation path: review the alignment page, provide feedback-only YAML or final approval YAML, then let the research skill write research/positioning-strategic-canvas.md.

Target

Current session: previous $ship-end closeout and current user correction.
Repository: /home/georgeqle/projects/web/dev/gblock-party-redux.
Primary skill contract: .codex/skills/ship-end/SKILL.md.
Related contracts: .claude/skills/ship-end/SKILL.md, .codex/skills/ship/SKILL.md, .codex/skills/exec/SKILL.md, .codex/skills/positioning/SKILL.md, and .codex/skills/positioning/frameworks/strategic-canvas/SKILL.md.
Task state: tasks/todo.md says Step 2 is awaiting review/approval before writing research/positioning-strategic-canvas.md.

Evidence Matrix

Claim	Evidence	Inference	Confidence	Decision impact
The next work was a research alignment approval gate.	`tasks/todo.md` Step 2: Strategic Canvas alignment page generated; blocker is approval/feedback before writing `research/positioning-strategic-canvas.md`.	The user action is part of the report-first research lifecycle, not an implementation setup task.	High	Do not route this to guided implementation walkthrough by default.
The positioning contract treats alignment review as the next action and suppresses downstream routing before approval.	`.codex/skills/positioning/SKILL.md`: report-first approval gate says to ask the user to review the alignment page and not include downstream routing until approved artifacts are written.	A shipping wrapper should preserve that distinction when it closes a session during a research approval pause.	High	Add explicit research/alignment routing before manual-work routing.
The Strategic Canvas contract confirms canonical research writes happen only after approval.	`.codex/skills/positioning/frameworks/strategic-canvas/SKILL.md`: "Default to report-only" and "Only after user approval" before output `research/positioning-strategic-canvas.md`.	The correct route is to continue the approval cycle, not to start a new manual guidance workflow.	High	The fix should classify this as a research approval continuation.
`$ship-end` lacks a separate research/alignment gate route.	`.codex/skills/ship-end/SKILL.md` routes external human-only manual work to `guided-walkthrough`, but has no rule for alignment-page approval blockers.	The current contract invites over-broad classification of any human review as guided manual work.	High	Patch the Next-Step Routing section.
Mirrored contract drift exists between Claude and Codex ship-end.	`diff -u .claude/skills/ship-end/SKILL.md .codex/skills/ship-end/SKILL.md` shows substantial differences; both still lack a dedicated research-alignment route.	A durable fix should update both mirrors or the source pack that generates them.	Medium	Route follow-up to a targeted skill update, not a one-off local edit.

Timeline

User invoked $ship-end.
The session shipped positioning alignment artifacts and marked Strategic Canvas Step 2 as awaiting approval/feedback.
The final report correctly named the next work as Strategic Canvas alignment review, but recommended $pack install guided-walkthrough.
User challenged that routing, noting research next-step detection should be distinct from implementation manual steps.
Current triage verified the mismatch against tasks/todo.md and the positioning/Strategic Canvas report-first contracts.

Root Cause

Classification: bad next-step routing caused by a missing route class and an insufficient evidence gate.

Specific gap: $ship-end distinguishes external human-only manual work and agent-executable work, but it does not distinguish report-first research/alignment approval gates. Because the next action involved human review, I mapped it to guided-walkthrough even though it was an alignment lifecycle pause inside a research skill.

Not the root cause: This was not a missing pack. guided-walkthrough being absent from .agents/project.json only explains why the recommendation was an install command. The more important failure is that guided-walkthrough was the wrong route for this class of next work.

Recommended Fix

Use $targeted-skill-builder to patch the source skill contract for ship-end, then refresh project-local generated skill roots. Apply the same rule to the mirrored Claude and Codex variants if the builder does not update both.

Proposed rule text

Research/alignment approval gates:
- If the next work is review, approval, feedback YAML, final compiled YAML, or confirmation for an alignment page under alignment/*.html, and the blocked artifact is a research/spec/positioning deliverable, classify it as a report-first research/alignment continuation.
- Do not route this to guided-walkthrough unless the task also requires an external human-only operational action such as browser-authenticated service work, DNS, paid account setup, dashboard-only configuration, real-device testing, or production sign-off.
- Recommended command: repeat the originating research skill only after approval YAML is available, or report "review the alignment page and provide feedback/approval YAML" with no downstream command when the active research skill contract says not to emit downstream routing before approval.
- If the approval gate is represented in tasks/todo.md rather than tasks/manual-todo.md, do not treat it as implementation manual work by default.

Placement

.codex/skills/ship-end/SKILL.md: ## Next-Step Routing, before the external human-only manual work bullet.
.claude/skills/ship-end/SKILL.md: matching ## Next-Step Routing section.
Consider applying the same classification in .codex/skills/ship/SKILL.md because it has similar routing rules and may close sessions after research approval pauses.

Validation Plan

Targeted text check: rg -n "Research/alignment approval gates|guided-walkthrough|alignment page" .codex/skills/ship-end/SKILL.md .claude/skills/ship-end/SKILL.md.
Mirror check: compare the Claude and Codex ship-end next-step routing sections and verify both contain the research/alignment route before external manual routing.
Replay check: using the current tasks/todo.md, the route should identify alignment/positioning-strategic-canvas-gblock-party.html approval as the next work and should not recommend $pack install guided-walkthrough.
Negative fixture: a task from tasks/manual-todo.md that blocks production smoke-test sign-off or service dashboard configuration should still route to $guide or $pack install guided-walkthrough.

Confidence & Gaps

Item	Status	What could change it
The previous recommendation was wrong for this research gate.	Evidence-backed	Only if the user intended a separate guided manual review workflow, which the task docs and positioning contracts do not indicate.
The durable fix belongs in `ship-end` routing.	Evidence-backed	If the source pack has a shared routing helper, the rule should move there instead of only local skill files.
Broad recurrence is unknown.	Unmeasured	Use `$analyze-sessions` only if we need frequency/trend evidence across prior sessions.

Review Gates

Research Completeness

Is the evidence sufficient to treat this as a verified $ship-end routing gap?

Yes, evidence is sufficient. Needs more evidence before changing the contract. Other / None of the above Need clarification

Recommended Fix

Should the next step be a targeted update to the ship-end routing contract?

Yes, use $targeted-skill-builder. Run broader session analysis first. Other / None of the above Need clarification

Compile

Use this if you want to approve or revise the triage recommendation as a durable report.