pal-e-docs

Skill: Review Ticket

skill-review-ticket Skill

active skill
Project

Skill: Review Ticket

Ticket scope reviewer agent workflow. Reads a board item's scope document, verifies file targets against the codebase, and creates a structured review note with a verdict.

Inputs

You receive from the router:
  • Board item metadata — title, item_type, labels
  • Scope reference — a Forgejo issue URL (the Forgejo issue IS the spec)
  • Project context — project page slug for architectural context

Steps

  • Read the Forgejo issue — Read the issue body via curl to the Forgejo API (extract owner/repo/number from the URL, use token from ~/secrets/pal-e-services/forgejo.env).
  • Identify the issue type — Read the ### Type header (Feature/Bug/Spike/Task). Route to the matching type-specific template: template-issue-feature, template-issue-bug, template-issue-spike, or template-issue (for Task — uses the base template with a Scope section instead of File Targets).
  • Check template completeness — Does the issue have all required sections for its type? List what's present and what's missing.
  • Verify traceability triangle — Check the three legs:
  • Verify file targets — For each file path mentioned in the issue (skip for Task type — Tasks have no file targets):
  • Check repo placement — Does the issue say the fix is in repo X, but the Forgejo issue is filed on repo Y? Are all affected repos identified? If the fix touches multiple repos, flag whether multiple Forgejo issues are needed.
  • Map dependencies — Read the board via mcp__pal-e-docs__list_board_items. Are there related items? Is this ticket blocked by something in in_progress? Does it block something else? Are dependencies documented in the scope?
  • Assess acceptance criteria — Could an agent verify each criterion after implementation? Are test commands real? Are there missing criteria?
  • Check blast radius — Use Grep to search for similar patterns in sibling services. If the ticket fixes a bug, does the same bug exist elsewhere? Are there downstream consumers affected?
  • Check decomposition need (5-minute rule) — Assess whether the ticket is too large for a single agent pass:
  • Determine verdict:
  • Create the review note — mcp__pal-e-docs__create_note with:
  • Post Forgejo comment — Post a summary comment on the Forgejo issue using mcp__forgejo__comment_on_issue: 
    ## Scope Review: {VERDICT}
Review note: `review-{board_item_id}-{date}`
{One-line summary of findings}
{If NEEDS_REFINEMENT or BLOCK: bullet list of issues}
{If decomposition needed: "Route to skill-decompose-ticket"}
  • Report verdict — Return your verdict and key findings to the caller. If verdict includes [DECOMPOSE], indicate that the caller should invoke skill-decompose-ticket with the board item ID and decomposition recommendations from the review note.

Review Note Format

MCP Tools

Step Tool Purpose
1 <code>Bash (curl)</code> or <code>mcp__pal-e-docs__get_note</code> Read scope document
2 <code>mcp__pal-e-docs__get_note</code> Read template
4a <code>mcp__pal-e-docs__get_section</code> Verify story entry exists on project page
4b <code>mcp__pal-e-docs__get_note</code> Verify arch note exists in pal-e-docs
5 <code>Read, Glob, Grep</code> Verify file targets
7 <code>mcp__pal-e-docs__list_board_items</code> Check board for dependencies
12 <code>mcp__pal-e-docs__create_note</code> Create review note
13 <code>mcp__forgejo__comment_on_issue</code> Post summary on Forgejo issue
  • skill-create-issue — creates scope from plan phases (upstream)
  • skill-decompose-ticket — decomposes oversized tickets into sub-boards (downstream, invoked on [DECOMPOSE] verdict)
  • template-issue — the template this skill validates against
  • template-ticket — board item conventions
  • sop-board-workflow — column semantics and flow rules
  • convention-agent-design — agents are workflows, not domains