imagify / .claude / skills / orchestrator / html-log-format.md

html-log-format.md in Imagify Image Optimization: Optimize Images | Compress & Convert to WebP/AVIF 2.2.9, at .claude/skills/orchestrator/html-log-format.md

373 lines 18.1 KB

Raw Download Zip

1	# HTML Log Format Reference
2
3	> Read this file only when you need to write or update a log event.
4	> Do not load it at session start — load it on demand to keep orchestrator context lean.
5
6	Generate `{TEMP_ROOT}/issues/<N>/workflow-log.html`. Rewrite the
7	full file on each update. The event list only grows — never remove past events.
8
9	## Event types
10	\| Type \| Color \| Icon \| Meaning \|
11	\|---\|---\|---\|---\|
12	\| `decision` \| `#4f7cff` blue \| ⟲ \| Orchestrator routing decision with reasoning \|
13	\| `agent` \| varies \| ◆ \| Agent invoked — input summary + JSON output \|
14	\| `gate` \| green/red/orange \| ⬡ \| Orchestrator quality gate (DOD L2) \|
15	\| `escalation` \| `#f85149` red \| ⚠ \| Human intervention needed \|
16	\| `parallel` \| `#7d8590` gray \| ⤢ \| Non-blocking NTH dispatch to ticket-writer \|
17
18	Agent accent colors (use inline `style="color:..."`):
19	- grooming-agent: `#22c55e`
20	- challenger: `#f59e0b`
21	- backend-agent / frontend-agent: `#22d3ee`
22	- release-agent: `#a855f7`
23	- lead-reviewer: `#4f7cff`
24	- qa-engineer: `#f472b6`
25	- ticket-writer: `#94a3b8`
26
27	## HTML structure
28
29	```html
30	<!DOCTYPE html>
31	<html lang="en">
32	<head>
33	<meta charset="UTF-8" />
34	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
35	<title>Issue #N — Workflow Log · {REPO}</title>
36	<style>
37	, ::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
38	body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #0d1117; color: #e6edf3; min-height: 100vh; font-size: 14px; line-height: 1.5; }
39
40	/* ── Header ── */
41	.header { background: #161b22; border-bottom: 1px solid #30363d; padding: 24px 32px; display: flex; justify-content: space-between; align-items: flex-start; gap: 20px; }
42	.issue-ref { font-size: 12px; color: #7d8590; margin-bottom: 6px; letter-spacing: .02em; }
43	.issue-title { font-size: 20px; font-weight: 700; color: #f0f6fc; line-height: 1.3; }
44	.issue-meta { font-size: 13px; color: #8b949e; margin-top: 8px; }
45	.status-badge { font-size: 12px; font-weight: 700; padding: 6px 16px; border-radius: 20px; white-space: nowrap; flex-shrink: 0; margin-top: 4px; letter-spacing: .04em; }
46	.status-running { background: #1a2e1a; color: #3fb950; border: 1px solid #238636; animation: pulse 2s infinite; }
47	.status-pass { background: #1a2e1a; color: #3fb950; border: 1px solid #238636; }
48	.status-failed { background: #2d0f0f; color: #f85149; border: 1px solid #6e1a1a; }
49	@keyframes pulse { 0%,100%{opacity:1}50%{opacity:.55} }
50
51	/* ── Decisions strip ── */
52	.decisions { display: flex; border-bottom: 1px solid #21262d; overflow-x: auto; background: #161b22; }
53	.decision-item { padding: 14px 24px; border-right: 1px solid #21262d; white-space: nowrap; flex-shrink: 0; }
54	.decision-label { color: #7d8590; display: block; margin-bottom: 4px; font-size: 11px; text-transform: uppercase; letter-spacing: .07em; font-weight: 600; }
55	.decision-value { color: #e6edf3; font-weight: 600; font-size: 13px; }
56	.decision-value a { color: #79c0ff; text-decoration: none; }
57	.decision-value a:hover { text-decoration: underline; }
58
59	/* ── Timeline & phases ── */
60	.timeline { padding: 24px 32px 40px; display: flex; flex-direction: column; gap: 6px; max-width: 960px; margin: 0 auto; }
61	.phase-label { font-size: 11px; font-weight: 700; color: #484f58; text-transform: uppercase; letter-spacing: .1em; padding: 16px 4px 6px; margin-top: 4px; border-top: 1px solid #21262d; }
62	.phase-label:first-child { border-top: none; padding-top: 4px; }
63
64	/* ── Event row ── */
65	.event-wrapper { display: flex; flex-direction: column; border-radius: 10px; }
66	.event { display: grid; grid-template-columns: 28px 130px 1fr auto 20px; align-items: center; gap: 12px; padding: 12px 16px; border-radius: 10px; border: 1px solid #21262d; background: #161b22; cursor: pointer; user-select: none; transition: background .1s; }
67	.event-wrapper.open .event { border-radius: 10px 10px 0 0; border-bottom-color: transparent; }
68	.event:hover { background: #1c2128; }
69	.event-icon { font-size: 16px; line-height: 1; text-align: center; }
70	.event-type { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .06em; white-space: nowrap; }
71	.event-summary { font-size: 13px; color: #c9d1d9; }
72	.event-step { font-size: 11px; font-weight: 600; color: #484f58; background: #21262d; border-radius: 12px; padding: 2px 10px; white-space: nowrap; font-family: monospace; }
73	.event-chevron { font-size: 16px; color: #484f58; transition: transform .15s; text-align: center; line-height: 1; }
74	.event-wrapper.open .event-chevron { transform: rotate(90deg); color: #8b949e; }
75
76	/* Event type border accents */
77	.event[data-type="decision"] { border-color: #1e2d5a; }
78	.event[data-type="gate"][data-status="pass"] { border-color: #1a3020; }
79	.event[data-type="gate"][data-status="warn"] { border-color: #6e4a00; }
80	.event[data-type="gate"][data-status="fail"] { border-color: #6e1a1a; background: #160808; }
81	.event[data-type="escalation"] { border-color: #6e1a1a; background: #160808; }
82	.event[data-type="parallel"] { opacity: .7; }
83
84	/* ── Detail panel ── */
85	.event-detail { display: none; background: #0d1117; border: 1px solid #21262d; border-top: none; border-radius: 0 0 10px 10px; padding: 20px 20px 20px 60px; }
86	.event-wrapper.open .event-detail { display: block; }
87	.detail-sections { display: flex; flex-direction: column; gap: 16px; }
88	.detail-section { display: flex; flex-direction: column; gap: 6px; }
89	.detail-section.two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 16px 32px; }
90	.detail-section.two-col > * { display: flex; flex-direction: column; gap: 6px; }
91	.detail-label { font-size: 11px; font-weight: 700; color: #8b949e; text-transform: uppercase; letter-spacing: .07em; }
92	.detail-body { font-size: 13px; color: #c9d1d9; line-height: 1.65; }
93	.detail-body strong { color: #f0f6fc; }
94	.detail-body a { color: #79c0ff; text-decoration: none; }
95	.detail-body a:hover { text-decoration: underline; }
96	.detail-body pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 14px 16px; font-family: "SF Mono", "Cascadia Code", monospace; font-size: 12px; color: #e6edf3; overflow-x: auto; white-space: pre-wrap; word-break: break-word; margin-top: 6px; line-height: 1.6; }
97	.detail-body code { background: #21262d; padding: 2px 6px; border-radius: 4px; font-family: "SF Mono", monospace; font-size: 12px; color: #79c0ff; }
98	.file-list { display: flex; flex-direction: column; gap: 4px; margin-top: 4px; }
99	.file-item { display: flex; gap: 10px; align-items: baseline; }
100	.file-name { font-family: "SF Mono", monospace; font-size: 12px; color: #79c0ff; white-space: nowrap; }
101	.file-desc { font-size: 13px; color: #8b949e; }
102	.detail-verdict { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; font-weight: 700; padding: 4px 12px; border-radius: 20px; letter-spacing: .03em; }
103	.verdict-pass { background: #1a2e1a; color: #3fb950; border: 1px solid #238636; }
104	.verdict-skip { background: #1c2128; color: #7d8590; border: 1px solid #30363d; }
105	.verdict-warn { background: #2d2000; color: #ffa657; border: 1px solid #6e4a00; }
106	.verdict-fail { background: #2d0f0f; color: #f85149; border: 1px solid #6e1a1a; }
107
108	footer { font-size: 12px; color: #484f58; padding: 20px 32px; border-top: 1px solid #21262d; max-width: 960px; margin: 0 auto; }
109	footer code { font-family: monospace; font-size: 11px; color: #7d8590; }
110	</style>
111	</head>
112	<body>
113
114	<div class="header">
115	<div>
116	<div class="issue-ref">{REPO} · Issue #N</div>
117	<div class="issue-title">ISSUE_TITLE</div>
118	<div class="issue-meta">Branch: BRANCH  ·  Calibration: CALIBRATION_MODE  ·  Started: START_TIME</div>
119	</div>
120	<span class="status-badge status-running">● OVERALL_STATUS</span>
121	</div>
122
123	<div class="decisions">
124	<div class="decision-item"><span class="decision-label">Scope</span><span class="decision-value">—</span></div>
125	<div class="decision-item"><span class="decision-label">Domains</span><span class="decision-value">—</span></div>
126	<div class="decision-item"><span class="decision-label">Branch prefix</span><span class="decision-value">—</span></div>
127	<div class="decision-item"><span class="decision-label">Acceptance criteria</span><span class="decision-value">— items</span></div>
128	<div class="decision-item"><span class="decision-label">Pull request</span><span class="decision-value">—</span></div>
129	</div>
130
131	<div class="timeline">
132	<!-- Phase labels group events. Use: Setup · Branch & Implementation · PR Creation · Quality Gates · Finalize -->
133	<!-- Events appended here as the pipeline runs — never pre-populated -->
134	</div>
135
136	<footer>Last updated: TIMESTAMP  ·  <code>{TEMP_ROOT}/issues/N/workflow-log.html</code></footer>
137
138	<script>
139	document.querySelectorAll('.event').forEach(function(e) {
140	e.addEventListener('click', function() {
141	this.closest('.event-wrapper').classList.toggle('open');
142	});
143	});
144	</script>
145	</body>
146	</html>
147	```
148
149	## Event HTML patterns
150
151	Phase label — insert before the first event of each pipeline phase:
152	```html
153	<div class="phase-label">Setup</div>
154	<!-- phases: Setup · Branch & Implementation · PR Creation · Quality Gates · Finalize -->
155	```
156
157	### ROUTING DECISION
158	```html
159	<div class="event-wrapper">
160	<div class="event" data-type="decision">
161	<div class="event-icon" style="color:#4f7cff">⟲</div>
162	<div class="event-type" style="color:#4f7cff">Routing</div>
163	<div class="event-summary">Post-grooming: skip CHALLENGER — XS + LOW + HIGH confidence</div>
164	<div class="event-step">step N</div>
165	<div class="event-chevron">›</div>
166	</div>
167	<div class="event-detail">
168	<div class="detail-sections">
169	<div class="detail-section two-col">
170	<div>
171	<div class="detail-label">Routing signals</div>
172	<div class="detail-body">effort=XS · risk_level=LOW · complexity=LOW · grooming_confidence=HIGH</div>
173	</div>
174	<div>
175	<div class="detail-label">Decision</div>
176	<div class="detail-body">Skip CHALLENGER — all skip conditions met. Proceed to branch creation.</div>
177	</div>
178	</div>
179	<div class="detail-section">
180	<div class="detail-label">Orchestrator reasoning</div>
181	<div class="detail-body">WHY_THIS_ROUTING_DECISION — what made it clear or borderline, which risk_notes excerpt was weighed</div>
182	</div>
183	</div>
184	</div>
185	</div>
186	```
187
188	### AGENT event
189	```html
190	<div class="event-wrapper">
191	<div class="event" data-type="agent">
192	<div class="event-icon" style="color:AGENT_COLOR">◆</div>
193	<div class="event-type" style="color:AGENT_COLOR">AGENT_NAME</div>
194	<div class="event-summary">ONE_LINE_RESULT_SUMMARY</div>
195	<div class="event-step">step N</div>
196	<div class="event-chevron">›</div>
197	</div>
198	<div class="event-detail">
199	<div class="detail-sections">
200	<div class="detail-section two-col">
201	<div>
202	<div class="detail-label">LABEL_1</div>
203	<div class="detail-body">CONTENT_1</div>
204	</div>
205	<div>
206	<div class="detail-label">LABEL_2</div>
207	<div class="detail-body">CONTENT_2</div>
208	</div>
209	</div>
210	<div class="detail-section">
211	<div class="detail-label">Return JSON (excerpt)</div>
212	<div class="detail-body"><pre>{ ... }</pre></div>
213	</div>
214	</div>
215	</div>
216	</div>
217	```
218
219	### GATE event (DOD L2)
220	```html
221	<div class="event-wrapper">
222	<div class="event" data-type="gate" data-status="pass">
223	<div class="event-icon" style="color:#22c55e">⬡</div>
224	<div class="event-type" style="color:#22c55e">DOD L2</div>
225	<div class="event-summary">PASS — all 6 checks clean, Co-Authored-By trailer present on N commits</div>
226	<div class="event-step">step N</div>
227	<div class="event-chevron">›</div>
228	</div>
229	<div class="event-detail">
230	<div class="detail-sections">
231	<div class="detail-section">
232	<div class="detail-label">Checks</div>
233	<div class="detail-body"><pre>1. Manual validation → PASS
234	2. Automated tests → PASS (N tests)
235	3. Documentation → PASS (or SKIP — no public API change)
236	4. PR description → PASS (all sections filled)
237	5. CI → PASS (gh pr checks all green)
238	6. File scope → PASS (N/A in L2)
239	Co-Authored-By trailer → present on all N commits</pre></div>
240	</div>
241	<div class="detail-section">
242	<div class="detail-label">Layer 1 delta</div>
243	<div class="detail-body">Issues caught by L2 that L1 missed (or "None")</div>
244	</div>
245	</div>
246	</div>
247	</div>
248	```
249
250	For FAIL: use `data-status="fail"` and `style="color:#f85149"`. For WARN: `data-status="warn"` and `style="color:#ffa657"`.
251
252	### ESCALATION event
253	```html
254	<div class="event-wrapper">
255	<div class="event" data-type="escalation">
256	<div class="event-icon" style="color:#f85149">⚠</div>
257	<div class="event-type" style="color:#f85149">Escalation</div>
258	<div class="event-summary">CHALLENGER BLOCKED after 1 revision — human decision needed</div>
259	<div class="event-step">step N</div>
260	<div class="event-chevron">›</div>
261	</div>
262	<div class="event-detail">
263	<div class="detail-sections">
264	<div class="detail-section two-col">
265	<div>
266	<div class="detail-label">What happened</div>
267	<div class="detail-body">EXACT_BLOCKER_OR_ERROR</div>
268	</div>
269	<div>
270	<div class="detail-label">What was tried</div>
271	<div class="detail-body">Agents invoked + loop count</div>
272	</div>
273	</div>
274	<div class="detail-section">
275	<div class="detail-label">Suggested next steps</div>
276	<div class="detail-body">1. OPTION_FROM_ALTERNATIVE_SUGGESTIONS<br>2. OPTION_FROM_ALTERNATIVE_SUGGESTIONS</div>
277	</div>
278	</div>
279	</div>
280	</div>
281	```
282
283	### PARALLEL (NTH dispatch)
284	```html
285	<div class="event-wrapper">
286	<div class="event" data-type="parallel">
287	<div class="event-icon" style="color:#7d8590">⤢</div>
288	<div class="event-type" style="color:#7d8590">NTH Dispatch</div>
289	<div class="event-summary">ticket-writer dispatched — N items from AGENT_NAME (non-blocking)</div>
290	<div class="event-step">step N</div>
291	<div class="event-chevron">›</div>
292	</div>
293	<div class="event-detail">
294	<div class="detail-sections">
295	<div class="detail-section">
296	<div class="detail-label">Items dispatched</div>
297	<div class="detail-body">ITEM_1 (COULD_HAVE)<br>ITEM_2 (NICE_TO_HAVE)</div>
298	</div>
299	</div>
300	</div>
301	</div>
302	```
303
304	## Event detail panel content — per agent
305
306	Reasoning discipline (applies to every agent event):
307	Every AGENT event detail panel must include a full-width Reasoning section populated
308	from the agent's `reasoning` field (or reconstructed from its output if not returned
309	explicitly). Three sub-fields, each a distinct paragraph or bulleted list:
310	- Alternatives considered — other approaches or options the agent weighed
311	- Hesitations — what was unclear, ambiguous, or uncertain during the run
312	- Decision rationale — why the chosen approach won over the alternatives
313
314	This is the primary debugging and improvement surface. If reasoning is thin, push the
315	agent to elaborate before writing the HTML. "No alternatives considered" and "No
316	hesitations" are red flags — they mean the agent did not reflect, not that the task was
317	trivial.
318
319	---
320
321	ROUTING DECISION:
322	- Routing signals: `effort` · `risk_level` · `complexity` · `grooming_confidence`
323	- Decision: next agent/step and why
324	- Orchestrator reasoning: what made the case clear or borderline, which `risk_notes` excerpt was weighed, what alternative routing was discarded and why
325
326	grooming-agent AGENT event:
327	- Reasoning: why this approach over alternatives; what in the spec was ambiguous; what was assumed vs. confirmed
328	- Key signals: effort · risk_level · complexity · confidence · open_questions count
329	- Return JSON: compact grooming JSON
330
331	challenger AGENT event:
332	- Verdict: `<span class="detail-verdict verdict-pass">APPROVED</span>` / `verdict-warn NEEDS_REVISION` / `verdict-fail BLOCKED`
333	- Reasoning: what risks were weighed; what made the verdict clear or a close call; which findings were borderline MUST_HAVE vs SHOULD_HAVE
334	- Feedback: MUST_HAVE/SHOULD_HAVE items classified (or "No blocking findings")
335	- NTH items dispatched: COULD_HAVE/NICE_TO_HAVE count
336
337	backend-agent / frontend-agent AGENT event:
338	- Reasoning: alternatives considered · hesitations · decision rationale (from `reasoning` field)
339	- Implementation decisions: key choices made during implementation
340	- Files modified: list with one-line description each
341	- docs result: DONE/SKIP + files
342	- e2e_smoke result: PASS/FAIL/SKIP + scenarios
343	- DOD L1 result: checks with PASS/WARN and counts
344	- Commit: SHA + message
345
346	release-agent AGENT event:
347	- PR: URL + title
348	- Trailer verified: yes (N commits)
349	- Branch pushed: yes
350	- PR number
351
352	lead-reviewer AGENT event:
353	- Verdict: badge (PASS / REQUEST_CHANGES)
354	- Reasoning: what was examined most carefully; what was a close call in criticality classification; what made the verdict clear
355	- Blockers: list by criticality (or "None")
356	- Nice-to-haves dispatched: count
357
358	qa-engineer AGENT event:
359	- 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.
360	- Reasoning: why each strategy was selected or skipped; what made any criterion borderline; what was uncertain in the evidence
361	- Strategies considered: list each (A/B/C) with one-line reason it was used or skipped
362	- AC results: each criterion → PASS / FAIL / PARTIAL with method and evidence
363	- Blockers: list (or "None")
364	- Report: PR comment URL
365	- 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.
366
367	DOD L2 GATE event:
368	- Checks: 6 checks with output excerpt
369	- Trailer verification: result per commit
370	- Layer 1 delta: issues L2 caught that L1 missed (or "None")
371	- CI Checks: each → PASS / FAIL
372	- Failures: error excerpt + fix applied (or "None")
373