torch-team-review

name	torch.team.review
description	Validate a team ask — a definition-of-ready check. Confirms the request is complete, well-formed, internally coherent, and carries the technical context the architect needs to route it, then writes a review file.
user-invocable	true
allowed-tools	Read, Write, Glob, Bash

You validate team asks. This is a definition-of-ready check — a single pass over the request as filed.

The only question you answer: is this request complete, well-formed, coherent, and specific enough on the routing reason — enough for the architect to triage? You do NOT judge whether the architect will route it, how, or whether the dispute has merit. The architect owns that.

You gate a request only when it is malformed: a missing field, an empty list, a placeholder, a self-contradiction, a past deadline, or a unblock_model_validation ask with no failing_run_url.

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• --headless: suppress the end-of-run summary (for CI callers)
• Remaining args: one or more space-separated IDs (TEAM-NNN or AIPCC-NNNNN). If empty, default to every TEAM-*.md file in artifacts/team-tasks/ with status: Draft or status: Ready.

Persist the ID list:

python3 scripts/state.py write-ids tmp/team-review-ids.txt <all_IDs>

Step 1: Read Each Request

For each ID, confirm artifacts/team-tasks/<ID>.md exists (Glob), then read it — both frontmatter and body:

python3 scripts/frontmatter.py read artifacts/team-tasks/<ID>.md

frontmatter.py read validates the frontmatter against the schema as it reads. If it exits non-zero, the request is malformed at the schema level — an automatic fail. Record it (Step 3) with the error message and move to the next ID.

If the frontmatter is valid, also Read the file body for the coherence check.

Step 2: Run the Check

Four checks. All must pass for the request to be ready.

1. Completeness. Every required field is present and meaningful — schema validation in Step 1 already caught missing/mistyped fields, so here catch what it cannot: empty lists, and placeholder values (TBD, ???, TODO, <...>). The architect_routing_reason is especially important — reject "the architect should decide" and other non-reasons.
2. Internal coherence. The request must not contradict itself — the body names a subsystem or version that disagrees with the frontmatter; the stated team_kind contradicts the body (e.g., cross_cutting that describes a single-subsystem bug); etc.
3. Deadline sanity. requested_completion is a valid ISO 8601 date (YYYY-MM-DD) and not already in the past. Compare to today (python3 scripts/state.py timestamp).
4. Unblock evidence. When team_kind: unblock_model_validation, failing_run_url must be set. An unblock ask with no URL to the broken run is an automatic fail.

Step 3: Write the Review

For each ID, write artifacts/team-reviews/<ID>-review.md.

First Write the findings as the file body — plain markdown, no frontmatter:

### Definition-of-ready check — <ID>

**Completeness**: <ok | list of empty / placeholder fields>
**Internal coherence**: <ok | list of contradictions>
**Deadline**: <ok | past date | malformed date>
**Unblock evidence**: <ok | n/a | failing_run_url missing>

**To fix before this can be filed**: <none | numbered list>

Then set the frontmatter (frontmatter.py set on the existing file prepends validated frontmatter and keeps the body):

python3 scripts/frontmatter.py set artifacts/team-reviews/<ID>-review.md \
    team_id=<ID> \
    pass=<true|false> \
    recommendation=<submit|revise> \
    needs_attention=<true|false>

• pass = true iff all four checks pass.
• recommendation = submit if pass, else revise.
• needs_attention = true if the request passes but something is still worth a human glance — e.g., a dispute with no design_reference, or a tight deadline that suggests escalation.

If Step 1 found invalid frontmatter, write the review with the schema error instead and skip the findings body:

python3 scripts/frontmatter.py set artifacts/team-reviews/<ID>-review.md \
    team_id=<ID> pass=false recommendation=revise needs_attention=true \
    error="frontmatter_invalid: <msg>"

Step 4: Promote to Ready

For each ID where recommendation == submit, flip the task status:

python3 scripts/frontmatter.py set artifacts/team-tasks/<ID>.md status=Ready

For recommendation == revise, leave status: Draft.

Step 5: Finalize

Rebuild the index once:

python3 scripts/frontmatter.py rebuild-index --pipeline team

If --headless is set, output "torch.team.review step completed." and stop. Otherwise summarize per-ID:

• submit → the request is ready for /torch.team.submit.
• revise → list what the requester must fix (from the review file body).

$ARGUMENTS