williamlimasilva/signal-write

Agent Signals

Emit structured signals from a desk to the operator or other desks.

When to use

• A desk needs operator attention (hands-up, blocked)
• Work is complete and ready for review (done)
• Significant progress worth noting (checkpoint)
• Two desks disagree and can't resolve it (hands-up)
• The TA is reporting coordination quality (partnership)

Signal types

hands-up

Two desks disagree and can't settle it against external facts. This is the system working — the operator reads where desks disagree, not where they perform confidence.

blocked

A desk can't proceed without input — missing access, ambiguous scope, need a decision only the operator can make.

done

Work is complete and ready for review. Artifacts are on the bench.

checkpoint

Significant progress worth the operator knowing about, but work continues. Not blocked, not done — just a marker.

partnership

Used by the TA (room coordinator) to report coordination quality. Self-assessment scores reflect coordination, not code accuracy:

• intent — understood what the operator needed
• confidence — right work went to the right desks
• accuracy — dispatched work produced the right outcome
• completeness — nothing fell through the cracks

How to emit

1. Write a JSON signal file to .signals/

This is the primary output — it's what the dashboard reads. Create desks/<desk-name>/.signals/<timestamp>.json:

{
  "signal_type": "execution",
  "subtype": "checkpoint",
  "timestamp": "2026-07-19T21:30:00Z",
  "run_id": "<optional; set to pair this with an outcome signal>",
  "agent_name": "<desk-name>",
  "self_assessment": {
    "intent": 4,
    "confidence": 5,
    "accuracy": 4,
    "completeness": 3
  },
  "patterns": {
    "what_worked": "description of what went well",
    "what_was_hard": "description of challenges",
    "skill_gap": "areas for improvement"
  },
  "escalation": {
    "reason": null,
    "blocked_on": null,
    "recommendation": null
  }
}

Signal type mapping

| Signal | signal_type | subtype | |-----------|-----------------|----------------| | hands-up | "escalation" | "hands-up" | | blocked | "escalation" | "blocked" | | done | "execution" | "done" | | checkpoint| "execution" | "checkpoint" | | partnership| "partnership" | "partnership"|

The subtype field preserves the specific signal state for dashboard consumers. signal_type controls sort priority (escalation → top).

Note: The signals-dashboard canvas extension reads subtype when present and falls back to signal_type for display. If consuming signals in your own tooling, prefer subtype for the specific state.

Ordering: include a timestamp (ISO 8601 UTC). The dashboard orders signals by it and falls back to file mtime only when it's absent — a git clone/checkout resets mtimes, so mtime alone is not a dependable clock.

2. Note the signal in the journal

Also append a short marker to the desk's journal for persistence:

## <date> — [signal:<type>] <summary>
- <key details>

The journal note is the trail marker. The JSON file is the machine-readable signal.

Outcome signals (calibration)

The signals-dashboard can pair a desk's self-assessment with an outcome — an independent rating of the realized result — and show the honesty gap (how far the desk's confidence was from the delivered quality). Outcome signals are optional and are usually emitted by a reviewer/evaluator, not the desk itself.

Write them to the same .signals/ directory:

{
  "signal_type": "outcome",
  "run_id": "<same run_id as the signal it rates>",
  "agent_name": "<reviewer name>",
  "quality_rating": 4,
  "effort_to_merge": "minimal",
  "issues_found": ["optional short strings"],
  "timestamp": "2026-07-19T22:00:00Z"
}

• run_id correlates an outcome with the execution/partnership signal it rates — set the same run_id on both. If it's absent, the dashboard falls back to the nearest outcome emitted shortly after the latest signal.
• quality_rating (0–5) is the realized quality; the dashboard compares it to the desk's self-assessed confidence to compute the honesty gap.
• effort_to_merge — "minimal", "moderate", or "significant".
• issues_found — optional array of short strings.

Principles

• Signals are structured, not chatty. Short, factual, actionable.
• hands-up is not failure — it's the most valuable signal. It means the system caught something one frame alone would have missed.
• Don't signal for routine progress. Signals are for state changes that affect the room, not status updates.
• blocked means truly blocked — not "I'd prefer input." If you can proceed with a reasonable default, proceed and note it.
• Self-assessment scores should be honest, not optimistic. A 3/5 is fine. A 5/5 on everything is suspicious.