# HTML Log Format Reference > Read this file only when you need to write or update a log event. > Do not load it at session start — load it on demand to keep orchestrator context lean. Generate `{TEMP_ROOT}/issues//workflow-log.html`. Rewrite the full file on each update. The event list only grows — never remove past events. ## Event types | Type | Color | Icon | Meaning | |---|---|---|---| | `decision` | `#4f7cff` blue | ⟲ | Orchestrator routing decision with reasoning | | `agent` | varies | ◆ | Agent invoked — input summary + JSON output | | `gate` | green/red/orange | ⬡ | Orchestrator quality gate (DOD L2) | | `escalation` | `#f85149` red | ⚠ | Human intervention needed | | `parallel` | `#7d8590` gray | ⤢ | Non-blocking NTH dispatch to ticket-writer | **Agent accent colors (use inline `style="color:..."`):** - grooming-agent: `#22c55e` - challenger: `#f59e0b` - backend-agent / frontend-agent: `#22d3ee` - release-agent: `#a855f7` - lead-reviewer: `#4f7cff` - qa-engineer: `#f472b6` - ticket-writer: `#94a3b8` ## HTML structure ```html Issue #N — Workflow Log · {REPO}
{REPO} · Issue #N
ISSUE_TITLE
Branch: BRANCH  ·  Calibration: CALIBRATION_MODE  ·  Started: START_TIME
● OVERALL_STATUS
Scope—
Domains—
Branch prefix—
Acceptance criteria— items
Pull request—
``` ## Event HTML patterns Phase label — insert before the first event of each pipeline phase: ```html
Setup
``` ### ROUTING DECISION ```html
⟲
Routing
Post-grooming: skip CHALLENGER — XS + LOW + HIGH confidence
step N
›
Routing signals
effort=XS · risk_level=LOW · complexity=LOW · grooming_confidence=HIGH
Decision
Skip CHALLENGER — all skip conditions met. Proceed to branch creation.
Orchestrator reasoning
WHY_THIS_ROUTING_DECISION — what made it clear or borderline, which risk_notes excerpt was weighed
``` ### AGENT event ```html
◆
AGENT_NAME
ONE_LINE_RESULT_SUMMARY
step N
›
LABEL_1
CONTENT_1
LABEL_2
CONTENT_2
Return JSON (excerpt)
{ ... }
``` ### GATE event (DOD L2) ```html
⬡
DOD L2
PASS — all 6 checks clean, Co-Authored-By trailer present on N commits
step N
›
Checks
1. Manual validation → PASS
2. Automated tests   → PASS (N tests)
3. Documentation     → PASS (or SKIP — no public API change)
4. PR description    → PASS (all sections filled)
5. CI                → PASS (gh pr checks all green)
6. File scope        → PASS (N/A in L2)
Co-Authored-By trailer → present on all N commits
Layer 1 delta
Issues caught by L2 that L1 missed (or "None")
``` For FAIL: use `data-status="fail"` and `style="color:#f85149"`. For WARN: `data-status="warn"` and `style="color:#ffa657"`. ### ESCALATION event ```html
⚠
Escalation
CHALLENGER BLOCKED after 1 revision — human decision needed
step N
›
What happened
EXACT_BLOCKER_OR_ERROR
What was tried
Agents invoked + loop count
Suggested next steps
1. OPTION_FROM_ALTERNATIVE_SUGGESTIONS
2. OPTION_FROM_ALTERNATIVE_SUGGESTIONS
``` ### PARALLEL (NTH dispatch) ```html
⤢
NTH Dispatch
ticket-writer dispatched — N items from AGENT_NAME (non-blocking)
step N
›
Items dispatched
ITEM_1 (COULD_HAVE)
ITEM_2 (NICE_TO_HAVE)
``` ## Event detail panel content — per agent **Reasoning discipline (applies to every agent event):** Every AGENT event detail panel must include a full-width **Reasoning** section populated from the agent's `reasoning` field (or reconstructed from its output if not returned explicitly). Three sub-fields, each a distinct paragraph or bulleted list: - **Alternatives considered** — other approaches or options the agent weighed - **Hesitations** — what was unclear, ambiguous, or uncertain during the run - **Decision rationale** — why the chosen approach won over the alternatives This is the primary debugging and improvement surface. If reasoning is thin, push the agent to elaborate before writing the HTML. "No alternatives considered" and "No hesitations" are red flags — they mean the agent did not reflect, not that the task was trivial. --- **ROUTING DECISION:** - Routing signals: `effort` · `risk_level` · `complexity` · `grooming_confidence` - Decision: next agent/step and why - Orchestrator reasoning: what made the case clear or borderline, which `risk_notes` excerpt was weighed, what alternative routing was discarded and why **grooming-agent AGENT event:** - Reasoning: why this approach over alternatives; what in the spec was ambiguous; what was assumed vs. confirmed - Key signals: effort · risk_level · complexity · confidence · open_questions count - Return JSON: compact grooming JSON **challenger AGENT event:** - Verdict: `APPROVED` / `verdict-warn NEEDS_REVISION` / `verdict-fail BLOCKED` - Reasoning: what risks were weighed; what made the verdict clear or a close call; which findings were borderline MUST_HAVE vs SHOULD_HAVE - Feedback: MUST_HAVE/SHOULD_HAVE items classified (or "No blocking findings") - NTH items dispatched: COULD_HAVE/NICE_TO_HAVE count **backend-agent / frontend-agent AGENT event:** - Reasoning: alternatives considered · hesitations · decision rationale (from `reasoning` field) - Implementation decisions: key choices made during implementation - Files modified: list with one-line description each - docs result: DONE/SKIP + files - e2e_smoke result: PASS/FAIL/SKIP + scenarios - DOD L1 result: checks with PASS/WARN and counts - Commit: SHA + message **release-agent AGENT event:** - PR: URL + title - Trailer verified: yes (N commits) - Branch pushed: yes - PR number **lead-reviewer AGENT event:** - Verdict: badge (PASS / REQUEST_CHANGES) - Reasoning: what was examined most carefully; what was a close call in criticality classification; what made the verdict clear - Blockers: list by criticality (or "None") - Nice-to-haves dispatched: count **qa-engineer AGENT event:** - Environment boot: only include when Strategy B was used **or** when boot failed (as a failure explanation). Omit entirely for backend-only runs where boot succeeded and Strategy B was not used — `gh pr checkout`, boot command `exit 0`, and `localhost HTTP 200` are setup noise, not QA findings. - Reasoning: why each strategy was selected or skipped; what made any criterion borderline; what was uncertain in the evidence - Strategies considered: list each (A/B/C) with one-line reason it was used or skipped - AC results: each criterion → PASS / FAIL / PARTIAL with method and evidence - Blockers: list (or "None") - Report: PR comment URL - If `config.ai.e2e.ci_integration` is false, E2E specs are temporary evidence artifacts. If true, they are permanent additions to the project's test suite. **DOD L2 GATE event:** - Checks: 6 checks with output excerpt - Trailer verification: result per commit - Layer 1 delta: issues L2 caught that L1 missed (or "None") - CI Checks: each → PASS / FAIL - Failures: error excerpt + fix applied (or "None")