Version 1 of 1 · · razie · in person · Current version

name
d3-f-guard-reports
description
Guardian runs and reports — the watches and where their checks live, starting and continuing a run, the Report topic and its findings, the notice after a run, and working the findings. Get skills only from /api/v2/skills/d3.
feature
guardians
concepts
[watch, report, finding]
tags
#skill #feature #d3skill #wip

d3-f-guard-reports

Intro

Guardian runs and their reports.

A guardian checks a project's work and only reports: one watch each (spec, tests, security, the watcher), one run at a time, one Report: topic per run. A watch's checks are actions (check_…) in the feature skills it watches; this skill is what every run shares — how it starts, what the report looks like, and what happens to its findings. Spec: Spec › guardians.

Essentials

  • R-guard-1 A run only reports: NEVER change topics, drafts, pipeline items, others' statuses or code — the one thing it writes is its report.
  • R-guard-2 MUST post the guardian status before reading or writing anything; until then the report write is refused.
  • R-guard-3 MUST continue an unfinished report (state: in-progress) in the same topic, never start over.
  • R-guard-4 MUST save as you go — after each check or every 5 items; state: done only when the run ends.
  • R-guard-5 MUST read published text only (/topics/, never /drafts/) and list the versions checked.
  • R-guard-6 Every finding quotes both sides and carries one Recommend: line that is actionable as it stands.
  • R-guard-7 A check you can't do is a finding of its own, saying why — NEVER skipped silently.
  • R-guard-8 Findings become work only on the person's word, with askedBy and a link to the report.

Concepts

watch

What one guardian checks. Also called: a guardian (the spec guardian, the watcher). One guardian per watch; the start prompt names it. A watch's checks are the check_… actions listed here, run in this order. The watches:

watch_add

  • Summary: a new watch adds check_… actions to the features it watches and a line to the watches list.
  • When: a design adds a watch.
  • Needs: its name, cadence, summary line and owners.
  • Call: — (edits to this skill and the watched features' skills, as drafts: d3-f-drafts › draft_save).
  • Rules: A check lives with the feature it checks, never here.
  • Errors: —
  • Gotchas: —

report

The Report: topic of one run (one pass of a watch's checks). Also called: the guardian report, a run. States: in-progress → done (kept in state).

report_start

  • Summary: status first; continue your watch's unfinished report, else start one and write it at once.
  • When: the start of every run.
  • Needs: your watch (from the start prompt).
  • Call: POST /api/v2/agents/status {agent: "guardian-<watch>", role: "guardian", state: "working", text: "<watch>"} (the watcher's board name is watcher) → find the newest Report:<watch>-guardian-… whose frontmatter watch is yours → state: in-progress: continue from its Run notes and through; otherwise PUT a new one, state: in-progress.
  • Rules: R-guard-2, R-guard-3. Never open another watch's report as yours.
  • Errors: E_SCOPE on the report write → no guardian status posted yet: post it, then write.
  • Gotchas: your newest report is in-progress but you can't read it → start a new one and say so in its Run notes. Why (R-guard-4): a long run that crashed half way started again from the top and crashed again.

report_read

  • Summary: published text only; history is evidence; quote, don't paraphrase.
  • When: every read a check makes.
  • Needs: —
  • Call: GET /api/v2/topics/<t> (+ its history for by and versions).
  • Rules: R-guard-5. Topic history shows drift, who changed a test, and creep. Skeptical by default: a claim with nothing to show for it (Tested, Built, As built) is a finding. Name items and sections as links, with a few words or their anchor.
  • Errors: —
  • Gotchas: —

report_finish

  • Summary: state: done, post idle, one notice with the summary line and link; an abstract in chat, never the report.
  • When: every check is done or recorded as not done.
  • Needs: the report saved.
  • Call: PUT the report with state: done → d3-f-board › status_post idle → d3-f-board › message_send to your person: summary line + link.
  • Rules: d2 raises N_GUARD for a run with findings (none for a clean run). In a chat: the summary line, the two or three findings that matter most, the link. Discuss, then act only when told (R-guard-8).
  • Errors: —
  • Gotchas: —

Name: Report:<watch>-guardian-<yyyy-mm-dd> (a second run the same day adds -2), titled Report from the guardian, . Fields (frontmatter): type: guardian-report, watch (the one property that says who wrote it), by (the agent's name), run (start time), since / through (the spec watch's done-items window), state, trigger, summary, checked (versions read, {Spec: 28, …}), tags: report, guardian.

report_write

  • Summary: summary line, a ## per check, findings in the fixed format, Run notes last; saved after each check.
  • When: from the first minute of the run, and after each check or every 5 items.
  • Needs: the report's current version (If-Match).
  • Call: PUT /api/v2/topics/Report:<watch>-guardian-<date> (raw markdown) — body: # Report from the <watch> guardian, <date>, the summary line, ## <check> sections, then ## Run notes (where you are, what's left, what you couldn't check and why).
  • Rules: R-guard-1, R-guard-4, R-guard-7. Any write other than this topic is refused — by design; report it instead.
  • Errors: E_SCOPE → no guardian status yet (see #report_start), or a write that isn't your report.
  • Gotchas: —

finding

One thing a check found. Format: ### F<n> <one line> {#f<n>}, then:

  • what you saw, where (links with anchors), what it differs from — quote both;
  • a context fence ```context <Topic>#<anchor> with a few lines around it as they are now, the problem line starting → (drift: two fences, the spec line and the test);
  • **Recommend:** — one line, concretely which line changes to what;
  • suggested items: - [ ] <title> {for: <role agent>, size: small|medium|large}.

finding_send

  • Summary: findings become items only when the person sends a report's batch, with askedBy and the report's link.
  • When: your person says to file or send them.
  • Needs: their word; the report's link.
  • Call: d3-f-pipeline › item_file with askedBy and a link to the report.
  • Rules: R-guard-8. A run files nothing on its own.
  • Errors: 202 {approval} → wait, don't retry.
  • Gotchas: —

finding_work

  • Summary: work each finding from its Recommend: line; pass on what isn't yours on the same batch.
  • When: a report's batch reaches you.
  • Needs: the report (it opens with what matters most; the spec report with Done items not carried, #not-carried, and one suggested item for all of them).
  • Call: GET /api/v2/topics/Report:<…>#f<n> → the change it recommends, in the owning feature's skill.
  • Rules: A gap marked for another role you pass on, same batch. Rules-vs-skills findings are fixed in the skill, never by loosening the ways-of-working doc people read.
  • Errors: —
  • Gotchas: —

Errors

  • E_SCOPE on the report write — no guardian status posted yet → post it, then write. see #report_start
  • E_SCOPE on any other write — a run only reports → put it in the report. see #report_write
  • N_GUARD (notice) — a run ended with findings. see #report_finish
  • newest report in-progress and unreadable — start a new one and say so in Run notes. see #report_start