docs(health): record day-to-day operating defaults for pyauto-brain health - #10
Merged
Merged
Conversation
…ealth Capture the conventions converged on during the first end-to-end Health Agent run: md mobile card as the default surface, severity-then-capability reason grouping, unknown-CI tiles kept secondary, an explicit local-checks-blind confidence downgrade when repos live outside PYAUTO_ROOT, fix-citation discipline, staleness handling, and the expected-first-run-gap vs real-problem separation. Presentation/triage only — the verdict is still adopted from Heart verbatim. Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an “Day-to-day defaults (operating agreement)” section to the Health Agent documentation so routine pyauto-brain health runs follow consistent presentation/triage conventions while still adopting PyAutoHeart’s verdict verbatim.
Changes:
- Documented default rendering order (mobile card first, then structured report).
- Recorded triage conventions for grouping, unknown/CI tiles, local-check blindness, staleness, and baseline first-run unknowns.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -123,6 +123,41 @@ Status: <GREEN | YELLOW | RED> (score <0-100>, snapshot <ts>) | |||
| - <red reason, mapped to its capability> (or "None") | |||
| ``` | |||
|
|
|||
| ## Day-to-day defaults (operating agreement) | |||
|
|
|||
| How `pyauto-brain health` should render and reason on a routine run. These are | |||
Comment on lines
+149
to
+151
| - **`fix` citations.** Cite a `pyauto-heart fix <ci|dirty|drift|timing>` entry | ||
| point **only when Heart's verdict names that failure class**. An unknown is | ||
| not a failure — never emit a fix for it. |
Comment on lines
+152
to
+154
| - **Staleness.** If `dashboard.stale == true`, or the snapshot `ts` is older | ||
| than the watch interval, downgrade confidence and recommend | ||
| `pyauto-heart tick` rather than trusting the stale board. |
Jammy2211
force-pushed
the
claude/health-agent-e2e-run-w5slh7
branch
from
July 3, 2026 08:23
f49c39a to
331e350
Compare
Comment on lines
+128
to
+130
| How `pyauto-brain health` should render and reason on a routine run. These are | ||
| presentation/triage conventions layered *on top of* the procedure above — they | ||
| never change the verdict, which is always adopted from Heart verbatim. |
Jammy2211
pushed a commit
that referenced
this pull request
Jul 3, 2026
Front-load the temporal clause so it no longer reads as the awkward "reason on a routine run". Same nit Copilot raised on the operating-agreement text in PR #10; fixed here too since the section lives in the vitals spec. Co-Authored-By: Claude <noreply@anthropic.com>
Front-load the temporal clause so the opening no longer reads as the awkward "reason on a routine run" Copilot flagged. Wording only. Co-Authored-By: Claude <noreply@anthropic.com>
…re-review) - `readiness.yellow_reasons` implied a nested JSON shape; readiness returns `yellow_reasons` at the top level. Reworded accordingly. - `pyauto-heart fix <ci|dirty|drift|timing>` read as literal syntax and clashed with the Procedure section's explicit forms; now `pyauto-heart fix <topic>` with the topics listed as examples. Co-Authored-By: Claude <noreply@anthropic.com>
…eview) - The "Grouping" bullet's "blocking-first" ordering contradicted the Output schema's fixed section order. Clarify it applies to ranking/triage and the dashboard card; the structured report keeps the schema order (Warnings, Recommendations, Blocking Issues). - Rewrap the Unknown-CI-tiles bullet to consistent line lengths. Co-Authored-By: Claude <noreply@anthropic.com>
Jammy2211
pushed a commit
that referenced
this pull request
Jul 6, 2026
…eview) Mirror the PR #10 fixes into the vitals spec: clarify that severity-first ordering applies to ranking/triage and the card (the structured report keeps the Output-schema section order), and rewrap the Unknown-CI-tiles bullet. Co-Authored-By: Claude <noreply@anthropic.com>
This was referenced Jul 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a "Day-to-day defaults (operating agreement)" section to
agents/health/AGENTS.md, capturing the presentation/triage conventions converged on during the first end-to-end run of the PyAutoBrain Health Agent.Why
The M5 unified-dashboard merge made this the first real
pyauto-brain healthrun. The run surfaced a set of rendering/triage decisions that weren't yet written down. Recording them means future runs inherit a consistent default instead of re-deriving it each time. These are presentation/triage conventions only — the verdict is still adopted from Heart verbatim; no gating logic is added or changed.What's in the note
pyauto-heart dashboard --mdmobile card, then the structured report.mainHEAD renders asCI in_progress(an unknown, not an active run) and doesn't enterreadiness.yellow_reasons; keep such tiles visually secondary.repo_stateispresent: false(repos outsidePYAUTO_ROOT), the local half of Heart observes nothing; say so and downgrade confidence rather than reading silence as verified-clean. Cite the one-timePYAUTO_ROOTfix.fixcitations — citepyauto-heart fix <ci|dirty|drift|timing>only when Heart's verdict names that failure class.pyauto-heart tickon a stale board.Scope
Single-file docs change (
agents/health/AGENTS.md, +35 lines). No code, no checks, no gating behaviour touched. Observer-only boundary preserved.🤖 Generated with Claude Code
https://claude.ai/code/session_01RLqU83iWW3R7ks33TzSyYs
Generated by Claude Code