arch-design-review

name	arch:design-review
argument-hint	[issue_number]
description	Posts design artefacts listed in design.yaml to GitHub one at a time, polls the issue for a reviewer reply, handles rejections with clarification comments, and marks the story ready-for-dev when all artefacts are approved. Fully driven through GitHub comments — no re-run required.
context	fork
allowed-tools	["Read","Bash","Write"]
write-paths	["docs/"]

Design Review Orchestrator

Manages the GitHub review and approval loop for all design artefacts produced by the architect. Posts each artefact as a separate GitHub comment, then polls the issue for a reviewer reply before posting the next one. The entire approval conversation happens inside the GitHub issue — no re-run needed between artefacts.

Callable standalone (after manual edits to any artefact) or from /arch:design-implementation.

Invocation:

/arch:design-review 460    # for a specific issue
/arch:design-review        # uses $AGENT_DOCS_DIR/active-story.yaml

Constraints

• Write: docs/ only (updates design.yaml approval state)
• Read: everything else — read-only
• Does not modify artefact files — only tracks approval state
• Does not self-approve; requires a non-bot commenter (issue author may approve)

---

Workflow

Step 1 — Resolve issue number

if [ -n "$ARGUMENT" ]; then
  ISSUE_NUMBER="$ARGUMENT"
else
  ISSUE_NUMBER=$(yq e '.issueNumber' "${AGENT_DOCS_DIR:-docs}/active-story.yaml" 2>/dev/null)
fi

if [ -z "$ISSUE_NUMBER" ] || [ "$ISSUE_NUMBER" = "null" ]; then
  echo "ERROR  No issue number. Pass one or run /github:story-fetch first."
  exit 1
fi

REPOSITORY=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
DESIGN_YAML="docs/stories/${ISSUE_NUMBER}/design.yaml"

Guard: if $DESIGN_YAML does not exist → exit with error:

ERROR  design.yaml not found: docs/stories/{id}/design.yaml
Run /arch:design-implementation {id} first to generate design artefacts.

Step 2 — Read design.yaml

Parse design.yaml to get:

• design.artefacts[] — full list with id, type, file, rationale, comment_id, approval_status
• design.approval_summary

If all artefacts already have approval_status: approved:

arch:design-review: all artefacts already approved — nothing to do

Exit 0.

Step 3 — Post summary comment (first run only)

If this is the first run (no summary comment previously posted — check by searching issue comments for <!-- design-implementation-summary -->):

<!-- design-implementation-summary -->
## Architecture Design Summary — Issue #{issue_number}

**{N} artefact(s) require approval before development can start.**

| # | Type | File | Status |
|---|------|------|--------|
| 1 | {type_label} | {file_path} | Pending |
...

**Reviewers:** reply `approved` (or `lgtm` / `yes`) or `rejected: <reason>` on each
artefact comment to proceed through the review.

Apply label architecture-in-review:

gh label create "architecture-in-review" --color "0075ca" --repo $REPOSITORY 2>/dev/null || true
gh issue edit $ISSUE_NUMBER --repo $REPOSITORY --add-label "architecture-in-review"

Step 4 — Artefact loop (repeat until all approved or a rejection exits)

Repeat the following sub-steps for each artefact in priority order:

4a — Gate check

Only proceed if every previously posted artefact has approval_status: approved. If any artefact is still pending or rejected, skip to Step 5 (status report) and exit.

Find the first artefact in design.artefacts[] order where comment_id is null and approval_status is not rejected. If none exists, all are posted — go to Step 4c (poll the last pending one) or Step 5 if none are pending.

4b — Post the artefact comment

Read the artefact file content.

Format the comment body:

<!-- design-approval-{artefact_id} -->
## Design Review: {type_label} — {artefact_id}

**Story:** #{issue_number} | **File:** `{file_path}`
**Rationale:** {rationale from design.yaml}

---

{file content inline:
  - ```mermaid fence for diagram_c4 / diagram_erd / diagram_flow
  - ```yaml fence for api_openapi / api_asyncapi / adr / implementation_plan
}

---

Reply **`approved`** (or `lgtm` / `yes`) to proceed, or **`rejected: <reason>`** to
request changes.

_Generated by /arch:design-review on {YYYY-MM-DD} — artefact {N} of {total}_

Type labels: adr → ADR | diagram_c4 → C4 Container Diagram | diagram_erd → ERD Diagram | diagram_flow → Flow Diagram | api_openapi → OpenAPI Contract | api_asyncapi → AsyncAPI Contract | implementation_plan → Implementation Plan

Post the comment and capture the ID and creation timestamp:

COMMENT_URL=$(gh issue comment $ISSUE_NUMBER \
  --repo $REPOSITORY \
  --body "$COMMENT_BODY" \
  --json url --jq '.url')
COMMENT_ID=$(echo "$COMMENT_URL" | grep -oE '[0-9]+$')
ARTEFACT_POSTED_AT=$(gh api \
  "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}" \
  --jq '.created_at')

Update design.yaml — set comment_id: {COMMENT_ID} for the artefact.

4c — Poll for reviewer reply

Identify the bot user (excluded from approval authority):

BOT_USER=$(gh api user --jq '.login' 2>/dev/null || echo "")

Poll in a loop until a qualifying reply appears. Between each check, sleep 30 seconds. Print a status line each iteration:

arch:design-review: waiting for review of {artefact_id} … (elapsed: {Nm})

On each iteration:

REPLIES=$(gh api "repos/${REPOSITORY}/issues/${ISSUE_NUMBER}/comments" \
  --jq "[.[] | select(
    .created_at > \"${ARTEFACT_POSTED_AT}\"
    and .user.login != \"${BOT_USER}\"
  )]")

Scan each reply body (trimmed, leading whitespace removed) for signals:

Approval signal matches ^(approved|lgtm|yes)\b (case-insensitive) → go to 4d.

Rejection signal matches ^(rejected|changes requested|nack|no)[:\s.] (case-insensitive) → go to 4e.

Continue polling if no signal found.

4d — On approval

Update design.yaml:

approval_status: approved
approved_by: "{commenter_login}"
approved_at: "{comment_created_at}"

Update approval summary (Step 5). Loop back to 4a for the next artefact.

4e — On rejection

Set approval_status: rejected in design.yaml. Reset comment_id: null (forces reposting on next run after revision).

Post clarification comment:

<!-- design-clarification-{artefact_id} -->
## Design Clarification Needed — {artefact_id}

Feedback received:
> {rejection_reason}

**Next steps:**
1. Revise `{file_path}` based on the feedback above
2. Re-run `/arch:design-review {id}` to repost the updated artefact for re-review

_Awaiting response before this story can proceed to development._

Update approval summary (Step 5). Exit the loop — do not post the next artefact.

Step 5 — Update approval summary in design.yaml

approval_summary:
  total_artefacts: {N}
  approved: {count approved}
  pending: {count pending}
  rejected: {count rejected}
  ready_for_dev: {true if approved == total_artefacts}

Step 6 — Complete or exit

If approved == total_artefacts:

gh label create "ready-for-dev" --color "0e8a16" --repo $REPOSITORY 2>/dev/null || true
gh issue edit $ISSUE_NUMBER --repo $REPOSITORY \
  --add-label "ready-for-dev" \
  --remove-label "architecture-in-review"

Post final summary:

<!-- design-approved -->
## All Design Artefacts Approved — Issue #{issue_number}

All {N} design artefacts have been approved. Story is ready for development.

| Artefact | Approved By | At |
|----------|-------------|----|
| {id} | {reviewer} | {timestamp} |

Next: assign the story and start implementation.

Update design.yaml:

status: approved

If a rejection was recorded in Step 4e: Print status table and exit.

arch:design-review: issue #{id} — review paused on rejection

  [x] adr-0014          — approved by alice (2026-03-29 14:03)
  [!] c4-container      — rejected by bob   (2026-03-29 14:21)
  [ ] api-payments      — queued
  [ ] implementation-plan — queued

Revise {file_path}, then re-run /arch:design-review {id}.

---

Output

Updates docs/stories/{id}/design.yaml with comment_id, approval_status, approved_by, approved_at for each artefact.

No new files written — artefact files are read-only from this skill's perspective.

---

Error Handling

Condition	Behaviour
design.yaml missing	Error: run /arch:design-implementation first
gh auth unavailable	Print gh auth login instructions and exit
Comment post fails	Log warning; comment_id stays null; retried on next run
All artefacts already approved	Print status and exit 0

---

Related Skills

Skill	Role
/arch:design-implementation	Orchestrator — calls this skill as final step
/arch:openapi-contract	Produces api_openapi artefacts reviewed here
/arch:asyncapi-contract	Produces api_asyncapi artefacts reviewed here
/arch:implementation-plan	Produces implementation_plan artefact reviewed here
/arch:adr-yaml + /arch:adr-render	Produce adr artefacts reviewed here
/github:mermaid-diagram	Produces diagram artefacts reviewed here