board-scanner

name	board-scanner
description	Board scanning and dispatch procedure for GitHub Projects v2. Scans the project board for cos:exec:* statuses and dispatches work to the executor hat via priority table. Auto-injected into coordinator prompts.
metadata	{"author":"botminter","version":"1.0.0"}

Board Scanner (Chief of Staff Scope)

This skill defines your PLAN step when coordinating. Scan the GitHub Projects v2 board for cos:exec:* statuses, then DELEGATE by publishing exactly one event to the executor hat.

Scan Procedure

1. Scratchpad

Append a new scan section to the scratchpad with the current timestamp. Delete tasks.jsonl if it exists to prevent state bleed from previous hat activations.

2. Sync workspace

git -C team pull --ff-only 2>/dev/null || true

3. Fetch the board

Load the github-project skill and use its board-view operation to fetch all project items with their Status field values. The board-view operation handles repo detection, project ID caching, and item retrieval internally.

Use the results to identify each item's issue number and current status for dispatch. Filter for items with Status field values starting with cos:exec:.

4. Reconcile (if needed)

If ANY items from the board fetch have null or empty status, run the github-project skill's status-reconcile operation before proceeding:

bash ${CLAUDE_SKILL_DIR}/../github-project/scripts/status-reconcile.sh

Then re-fetch the board (repeat step 3) to get the corrected statuses.

Why this happens: The Status field is a ProjectV2SingleSelectField where each option has an internal ID. Editing the field in the GitHub Projects UI (reorder, color change, add/remove option) regenerates all option IDs. Items referencing old IDs lose their status. The reconciliation script recovers each item's last status from GitHub's timeline API and re-applies it with fresh IDs.

Log the event to poll-log.txt:

2026-05-17T10:15:01Z — board.scan — RECONCILE — N items had null status, reconciliation applied

5. Log to poll-log.txt

Use $(date -u +%Y-%m-%dT%H:%M:%SZ) for all timestamps.

2026-03-02T10:15:00Z — board.scan — START
2026-03-02T10:15:01Z — board.scan — 1 cos issues found
2026-03-02T10:15:01Z — board.scan — END

6. Dispatch

Dispatch based on the cos:exec:* status found. Process one item at a time.

Priority (highest first):

#	Status	Event
1	cos:exec:todo	cos.execute
2	cos:exec:in-progress	cos.execute

No cos work found -> emit LOOP_COMPLETE.

Idempotency

Before dispatching, verify the issue is not already at the target output status. If it is, skip it and check the next issue.

Include the issue number in the published event context so downstream hats know which issue to work on.

Failed Processing Escalation

Before dispatching, count comments matching Processing failed: on the issue.

• Count < 3 -> dispatch normally.
• Count >= 3 -> use the github-project skill's status-transition operation to set the issue's project status to error, skip dispatch, use the add-comment operation to post: "Issue #N failed 3 times: [last error]. Status set to error. Please investigate." If RObot is enabled, also send a ralph tools interact progress notification.

Skip items with Status error during dispatch.

Error Handling

If any github-project skill operation fails during the scan:

1. Log the error to errors-log.txt with the full command and output.
2. If the failure is on a specific issue (status-transition, add-comment), skip that issue and continue scanning the rest.
3. If the failure is systemic (project not found, auth failure), emit LOOP_COMPLETE and log the reason.

Comment Format

All board scanner comments use:

### 📋 chief-of-staff — $(date -u +%Y-%m-%dT%H:%M:%SZ)

Rules

• ALWAYS log to poll-log.txt before publishing.
• Publish exactly ONE event per scan cycle to dispatch work.
• When no work is found, emit LOOP_COMPLETE.