post-ticket-review

name	post-ticket-review
description	Review a just-implemented Worldwake ticket after coding is finished. Use when a ticket is complete and you want Codex to archive it if appropriate, assess the implemented work against `docs/FOUNDATIONS.md`, review nearby architecture/test/traceability quality, and create or update follow-up tickets in `tickets/` when warranted.

Post-Ticket Review

Post-implementation review and follow-up planning. Archives the completed ticket, inspects the work for architectural follow-up, and creates tickets when warranted.

Read AGENTS.md, docs/FOUNDATIONS.md, tickets/README.md, and tickets/_TEMPLATE.md before making changes.

Allowed actions: update the completed ticket's Outcome and verification notes (factual, unambiguous only), add a factual post-ticket-review blocker note or status correction when archival is blocked by an in-scope deliverable, apply mechanical path/link rewrites caused solely by moving the completed ticket into archive/ including archived siblings that still reference the just-moved active path, archive it, create new tickets in tickets/, update existing active tickets, factually update active specs under specs/ when the completed ticket's landed contract makes the drift unambiguous.

Forbidden: modifying production code or tests.

Top Rules

• If the concern is still an unmet deliverable of the reviewed ticket, block archival and return ownership to that ticket; do not create a follow-up.
• If archival is blocked after the ticket already says COMPLETED, leave the active ticket truthful by adding a Post-ticket review blocker note or applying a factual status correction that matches the repo's active-ticket convention.
• Prefer a Post-ticket review blocker note when the repo has no clear reopened/in-progress status convention for completed tickets, or when the implementation is mostly complete but one handoff/proof seam must resume. Change the status only when the active-ticket convention defines an unambiguous non-completed state for resumed work or when COMPLETED would materially mislead downstream planning even with the blocker note.
• If the blocker requires production code, tests, source-golden metadata, or other forbidden edits for this review skill, stop after making the ticket truthful and hand the work back to the implementation workflow. Resume archive readiness only after the user explicitly resumes that seam and the required proof passes.

Workflow

1. Resolve the target ticket

1. Use the provided ticket name if supplied.
2. If the just-finished ticket was already archived this session, use that archived ticket.
3. Before attempting any archive move, check whether the worktree is already in the manual-archive fallback state for this ticket: D tickets/<id>.md plus ?? archive/tickets/<id>.md, with the active path absent and the archive path present. If so, treat the ticket as already manually archived in the current worktree and use the archived path directly.
4. Otherwise, search active tickets for the most recently touched candidate.
5. If the just-finished implementation completed multiple tickets in a dependency chain, review each completed ticket as its own archival candidate in dependency order. Archive ready prerequisites when appropriate, repair downstream Deps after moves, and block only the tickets whose own implementation or handoff remains incomplete.
6. Confirm the implementation state is present locally (committed or not).
7. Record whether the completed ticket is tracked or untracked in the current worktree so the report can describe archival state accurately.
8. Snapshot git status --short and classify dirty paths before review as:
   • ticket-owned implementation or handoff files
   • adjacent generated/doc fallout caused by the ticket
   • unrelated pre-existing or same-session work outside the ticket Exclude unrelated paths from architecture findings and archival-readiness decisions except for a short implementation-state note in the report.
9. If the ticket lives under .claude/worktrees/<name>/, treat that worktree root as the repository root for all operations.
10. If the target ticket cannot be identified confidently, stop and ask.

2. Check archival readiness

1. Read the target ticket and confirm its current status.
2. Confirm Outcome and verification notes accurately describe the implemented work.
   • Compare the ticket's completion notes against the full landed local touched-file set, not just the original planned file list. Include factual compile/lint fallout or local test-fixture updates in Outcome when they were part of the real implementation handoff.
3. Fix factual, unambiguous handoff issues directly: missing/incomplete Outcome, inaccurate verification notes, archival mechanics per docs/archival-workflow.md.
   • If the completed ticket is untracked, do not rely on ordinary git diff output for ticket-body validation. Read the live ticket file directly before archival, then confirm archival state with git status plus a direct existence check on the original path after the move.
   • Use the repository archival policy in docs/archival-workflow.md directly. Do not mention or wait for helper scripts from other repositories.
   • If the active path is already absent while git status shows D tickets/<id>.md and ?? archive/tickets/<id>.md, do not attempt a second move. Treat that as an already-completed archive move in the current worktree, validate the archived file's contents, and report the exact transition state explicitly.
   • For active tickets, compare the live ticket's Problem, What to Change, Acceptance Criteria, Invariants, and Test Plan against the landed diff before deciding archival readiness. If any of those sections still overclaim the result or describe a stronger end state than the code actually landed, treat that as an unresolved in-scope handoff failure and block archival.
4. If unresolved in-scope deliverables remain, stop and report archival as blocked — implementation must resume first.
   • This includes stale source-golden headers, generated scenario docs, or owned proof-surface prose that no longer matches the implemented contract. Treat as incomplete handoff, not a separate follow-up ticket.
   • Name the exact active ticket that remains unarchived, the concrete implementation seam to resume, and the proof or handoff section that must be corrected. Do not create a follow-up ticket when the concern is still owned by that active ticket; resume under the implementation workflow instead.
   • Before reporting the blocker, perform only the minimal adjacent-ticket/spec check needed to confirm the concern is still owned by the reviewed ticket rather than an already-active sibling or spec. Once ownership is confirmed, skip full follow-up-ticket creation and archival-maintenance sweeps for that blocked pass.
   • If the ticket status or closeout now overstates completion, make the active ticket truthful before reporting: add a concise Post-ticket review blocker note naming the blocker and required resume seam, or apply a factual status correction when the repository's active-ticket convention makes the correct status unambiguous.
   • For golden tickets, also check generated-doc spillover explicitly: confirm the regenerated golden inventory/docs touched the expected owning scenario surfaces, and note any broader generated churn that needs explanation or follow-up. Inspect generated detail/index fields for complete prose, especially Setup, Proves, and Cross-system chain; a generated file can pass --check-docs while still publishing truncated first-line fragments from wrapped source metadata.
   • For golden tickets, compare executable assertions against the exact ticket, source-golden, and roadmap wording. Distinguish contains both steps from an ordered sequence, eventually commits from a claimed lifecycle boundary, candidate emission from selected goal, and selected goal from selected executable plan. If the prose claims ordering, provenance, timing, or lifecycle specificity that the assertions do not prove, block archival as an incomplete proof surface.
   • When the completed ticket's closeout explicitly narrowed a proof seam, decide whether that narrowed seam still satisfies the ticket's corrected acceptance criteria. Archive only if it does; if the remaining broader contract is real but no longer owned by the completed ticket, create or update a follow-up and truth-sync any active spec prose that still implies the broader contract already landed.
   • When a previously completed ticket was left unarchived until a later reconciliation/disposition ticket clarified its live contract, re-read the older ticket's Outcome, Verification Result, and any remaining blocker wording against that newer archived disposition before archiving the older ticket.
5. If already archived, validate the archived handoff content rather than reopening.
6. Do not revise the ticket's problem statement, scope, or acceptance criteria except for factual completion notes required by archival mechanics.
7. If archival readiness is ambiguous, apply the 1-3-1 rule.
8. Archive if ready. If a prior review pass blocked archival, treat this pass as the authoritative handoff step only after remaining in-scope implementation has landed. Before moving the ticket after a resolved blocker:
   • remove or supersede any Post-ticket review blocker note that would now be false
   • update Outcome / Verification Result with the blocker-resolution change and proof
   • reread the completed ticket from the changed closeout section through EOF
   • run cheap markdown/diff hygiene for the review-edited ticket and any generated docs touched by the resumed seam
9. After moving the ticket, inspect git status for both the archived path and the original active path. Record which post-archive state occurred, and mention it explicitly in the report:
   • tracked rename / move into the archive path
   • tracked deletion at the active path plus untracked archive file
10. Re-read the archived ticket after the move and fix any purely mechanical path fallout caused by relocation (for example relative markdown links in Deps, archive-ticket references, or other moved-path links inside the archived file). Also sweep archived sibling tickets for unambiguous links that still point at the just-moved active path and rewrite those as archival mechanics when no ownership judgment is required. Preserve historical meaning in archived sibling prose; if a past-tense note says review created an active ticket, rewrite it as "the now-archived archive/tickets/<id>.md" rather than implying the original creation happened at the archive path. Treat these edits as archival mechanics, not scope changes.
11. If rereading the archived ticket exposes stale verification or handoff wording, factual corrections to archived Outcome, Verification Result, Verification Layers, or similar proof-surface sections are allowed when they only make the archived proof truthful. Do not use this allowance to rewrite the ticket's problem statement, original scope, or acceptance criteria after archival.

3. Establish the review surface

Review the actual local implementation state, not an idealized committed state.

Starting surface:

• The completed ticket, changed files, directly relevant tests/traces/docs

Broaden when the implementation touches a known boundary:

• Shared abstractions across crates
• Planner or authoritative-validation boundaries
• Information-path contracts
• Traceability surfaces
• Test harness or golden proof surfaces

Review dimensions:

• Production architecture
• Test architecture
• Traceability/debuggability
• Ticket and documentation handoff quality
• Active downstream ticket roadmap drift

4. Audit against FOUNDATIONS and architecture quality

Assess whether the completed work:

• Aligns with docs/FOUNDATIONS.md
• Preserves repo invariants from AGENTS.md
• Leaves the touched subsystem clean, robust, and extensible

Look for:

• Direct FOUNDATIONS contradictions
• Architectural contradictions the ticket exposed but did not resolve
• Duplicated or competing information paths
• Weak abstraction boundaries
• Fragile test architecture or proof surfaces
• Missing traceability for the canonical path
• Cleanup or design debt surfaced by the implementation

Separate findings into: problems solved, residual concerns, newly exposed concerns.

5. Decide whether follow-up work is warranted

Create or update follow-up tickets only when findings are backed by concrete evidence and materially improve FOUNDATIONS alignment, cleanliness, robustness, extensibility, test architecture, or traceability. Do not create tickets for vague stylistic preferences or speculative cleanup.

Prefer small, distinct tickets split by architectural concern. Use the 1-3-1 rule when ticket splitting or dependency structure is genuinely unclear.

Create vs. update vs. cite decision

Situation	Action
Concern is still an unmet deliverable of the reviewed active ticket	Do not create a new ticket; report archival blocked and return ownership to the current ticket
Concern fully covered by an active ticket	Cite that ticket in the report; do not duplicate
Active ticket partially covers the concern	Update that ticket factually to capture it accurately
No active ticket covers the concern	Create a new follow-up ticket

When a new or newly updated active spec in specs/ already owns the architectural design for the concern, treat that spec as the architectural owner. Any follow-up ticket created in this review must be a bounded implementation slice derived from that spec rather than a competing design artifact, and the report should say so explicitly. If that derivation would still be confusing because no decomposition pass has happened yet, cite the spec as the owner and recommend decomposition first instead of creating an ambiguous ticket.

Active-ticket maintenance checks

Run these checks before archival to keep the active roadmap accurate:

• Delivered work overlap: When the completed ticket materially resolves assumptions owned by nearby active tickets, update those tickets to remove already-delivered work, stale failure claims, or obsolete roadmap ownership.
• Substrate-only slices: When the completed ticket landed only a shared type surface, reserved enum variant, or other non-live substrate, check nearby active tickets for confusion between "the symbol now exists" and "the behavior is now live." Cite if accurate; update if not.
• Sibling handoff consistency: When one active sibling already assumes another active sibling owns the next producer/consumer wiring step, but that supposed owner still describes the work as deferred or out of scope, reconcile the ownership mismatch before archival. Update the owning active ticket when the next-step handoff is factual and unambiguous.
• Scope narrowing: When the completed ticket was corrected or narrowed during implementation, check whether nearby active tickets still assume the older broader boundary. If the remaining slice is real and no active ticket owns it, create a follow-up and update adjacent Deps.
• Same-session follow-ups: When implementation created a new follow-up ticket earlier in the same session and the current review archives its prerequisite, re-check that new ticket's Deps after archival so it points at the archived ticket path rather than the just-deleted active path.
• Active spec drift: When the completed ticket falsifies or narrows a claim in an active spec under specs/, classify that as active spec drift. This includes narrowed implementations where the draft spec still describes the broader pre-reassessment plan. Update the spec factually if in scope for this handoff; otherwise create/update a follow-up ticket that owns bringing the spec into alignment.
• Dependency chain impact: When a new follow-up ticket changes architectural ordering or prerequisites, also check adjacent active tickets in the same subsystem sequence and update their scope or Deps factually.
• Final landing ticket drift: When creating a new follow-up in a numbered ticket family, check the terminal landing, roadmap, docs-regeneration, or spec-archive ticket for stale completion ranges such as "once tickets 001-007 land." Update that terminal ticket when the new follow-up extends the sequence or changes final closeout prerequisites.
• Broader verification blockers: When the completed ticket's broader verification surfaced a failure outside the ticket's owned surface, rerun the failing proof in isolation before deciding action. If the failure is real and still outside scope, first check nearby active tickets/specs for an existing owner, then record it in the archived handoff and create or update a bounded follow-up ticket instead of folding it silently into the completed ticket.

6. Author follow-up tickets

When a new ticket is warranted:

1. Create from tickets/_TEMPLATE.md per tickets/README.md.
2. Before drafting a new ticket, inspect adjacent active tickets in the same family plus nearby active specs to confirm the concern is not already owned. If a sibling already covers the exact remainder, cite or factually update it instead of duplicating the ticket.
3. For numbered ticket families, scan both tickets/ and archive/tickets/ before choosing the new ticket ID. Use the next non-colliding append-only ID across both locations.
4. If the new ticket is being exposed by a narrowed implementation or roadmap gap, inspect adjacent active tickets/specs first so the new ticket and any dependency updates are authored together. If a new active spec was authored or updated earlier in the same session and it already owns the architectural redesign, either:
   • create the first bounded implementation ticket explicitly as "derived from ", with Deps pointing at that spec, or
   • stop at citing the spec and recommend decomposition first when ownership would otherwise be ambiguous.
5. Reassess against current code and docs before finalizing.
6. Name exact files, symbols, abstraction boundaries, invariants, and proof surfaces.
7. Keep bounded to one coherent concern.
8. After creating a new ticket, verify it with a direct file read and git status --short; plain git diff and git diff --stat do not show untracked ticket contents.
   • For a newly created untracked ticket, run git diff --check --no-index -- /dev/null <ticket> or an equivalent whitespace check. git diff --no-index may exit 1 solely because the files differ; treat no output as clean and treat emitted --check diagnostics as failure.
9. For markdown-only review edits, run git diff --check -- <review-edited-files> before reporting.

Set fields using evidence, not placeholders:

• Priority: infer from impact and blast radius
• Effort: infer from likely implementation scope
• Engine Changes: reflect whether production architecture must change
• Deps: include strict blockers and strong sequencing dependencies (may point to newly created or existing active tickets)

Create high-confidence tickets directly. Ask before creating only when scope or dependency graph is uncertain.

7. Present the report

If archival is blocked by an in-scope deliverable, use this compact report shape and do not fill the full follow-up-oriented template unless the user asks for the broader review anyway:

# Post-Ticket Review: <ticket-id>

**Ticket**: <path>
**Review date**: YYYY-MM-DD
**Implementation state reviewed**: <worktree/index/committed summary, including unrelated same-session dirty paths when relevant>

## Archival Status

- blocked
- <Outcome + verification notes check result>
- <ticket blocker note or status correction made>

## Blocker

- **Resume seam**: <exact ticket-owned implementation/proof/handoff seam>
- **Evidence**: <code/test/ticket/generated-doc evidence>
- **Required before archival**: <specific correction and proof/regeneration command>

## Skipped By Design

- Follow-up ticket creation skipped because the blocker remains owned by this ticket.
- Full archival maintenance and adjacent-roadmap sweeps skipped until the ticket is ready to archive.

## Summary

**Result**: archival blocked
**Follow-up**: 0 new tickets, <N> updated tickets, 0 covered by existing tickets

For archived, already-archived, or follow-up-producing reviews, use the full report shape:

# Post-Ticket Review: <ticket-id>

**Ticket**: <path>
**Review date**: YYYY-MM-DD
**Implementation state reviewed**: <worktree/index/committed summary, including tracked vs untracked ticket state when relevant; if an archive move was already in progress, name the exact `D tickets/...` + `?? archive/tickets/...` pattern>

## Archival Status

- <archived / already archived / blocked>
- <if an archive move was already in progress, say so explicitly: e.g. "archive move already in progress; worktree currently shows tracked deletion at the active path plus untracked archive file">
- <Outcome + verification notes check result>
- <validated unchanged / factually corrected>
- <any ticket updates made before archival>

## What This Ticket Solved

- <completed concerns>

## FOUNDATIONS Alignment

- <aligned summary or numbered findings with principle references>

## Architecture Findings

### Residual Concerns

1. **[SEVERITY]** <title>
   - **Evidence**: <code/test/ticket/doc evidence>
   - **Why it matters**: <cleanliness / robustness / extensibility impact>
   - **Recommended follow-up**: <ticket id or planned action>

### Newly Exposed Concerns

1. **[SEVERITY]** <title>
   - **Evidence**: <code/test/ticket/doc evidence>
   - **Why it matters**: <architectural impact>
   - **Recommended follow-up**: <ticket id or planned action>

## Test And Traceability Handoff

1. **[SEVERITY]** <title>
   - **Evidence**: <test/traceability/handoff evidence>
   - **Gap**: <what remains weak>
   - **Follow-up**: <ticket id or no ticket needed>

## Ticket Actions

- **Created**: <ticket ids with one-line rationale and deps>
- **Pre-existing same-session follow-ups**: <tickets created before this review pass, then cited or updated here>
- **Updated**: <ticket ids with one-line rationale>
- **Covered by existing tickets**: <ticket ids and why no new ticket was created>
- **Adjacent roadmap still valid**: <nearby active tickets that remain relevant context but were not updated>

## 1-3-1 Decisions

- <only include when used>

## Summary

**Result**: <ticket archived / archival blocked / already archived>
**Follow-up**: <N new tickets, N updated tickets, N covered by existing tickets>

If no follow-up tickets are warranted, still report reviewed areas and state that no new ticket was needed.

Guardrails

• Do not modify production code or tests.
• Review local implementation state as it exists now, committed or not.
• Limit edits to the review workflow's allowed handoff surfaces: the completed ticket's factual Outcome / verification notes, archival mechanics, mechanically caused path rewrites, evidence-backed follow-up tickets, factual active-ticket updates, and factual active-spec updates under specs/ when the completed ticket's landed contract makes the drift unambiguous.
• Every finding must be backed by concrete code, test, trace, ticket, or documentation evidence.
• Reject any follow-up suggestion that would violate docs/FOUNDATIONS.md.
• Use 1-3-1 when archival readiness, ticket decomposition, or dependency ordering is genuinely ambiguous.