[Peeja]

Written by Claude.

Depends on #248. The new section points to the severity definitions that PR adds, so merge it first.

This adds a short Observability section to AGENTS.md. When a change adds or alters something operational, the section tells an agent to decide how on-call would see it fail and to add what's useful in the same PR: an alert, a dashboard panel, or a line in docs/observability.md. It also says to skip this for changes nothing operational depends on.

The section is kept short because AGENTS.md loads into every session. That follows bajtos's review of fil-forge/infra-nodes#174. The how-to lives in a new "Adding an alert or panel" section of docs/observability.md. It lists the labels each rule needs (team_name, component, a severity chosen by the definitions #248 adds, stage, notification_settings), notes that check-alert-routing.sh enforces routing and that new rules go last because uids follow position, describes dashboard JSON with normalise-dashboard.sh, and says application metrics don't ship yet.

This PR no longer adds a CLAUDE.md. Claude Code reads AGENTS.md itself from v2.1.277 (docs).

Companion PRs: fil-forge/piri#174, fil-forge/infra-nodes#174 and the Forge service repos.

Checks

• make check, git diff --check.

✴️

🤖 Generated with Claude Code

https://claude.ai/code/session_01JCF8gyb8jNRmHmWqQmVhRJ

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[Peeja]

Claude reviewer says… (1st round, 0a1e717)

Approve with nits; nothing blocking or should-fix.

Verified

• Required labels: all 25 rules carry team_name = "forge", a severity and policy = local.forge_policy.
• Routing check: check-alert-routing.sh runs on the Grafana plan (check-and-deploy.yml:529).
• Dashboard normalisation: make check runs normalise-dashboard.sh --check.
• Panel links: dashboard_url, __dashboardUid__ and __panelId__ are used on 12-13 rules.
• Application metrics: "Not shipped. Application metrics" is at observability.md:21.
• Severity definitions: they come from Define alert severities in the observability docs #248, and the body says so.
• Checks: make check passes and git diff --check is clean.

Findings

1. nit, required labels.
   • Every rule also has a component label.
   • "The rule group for the component" is ambiguous, because the appliance has three groups.
   • stage comes from the query on Central rules but from local.appliance_stage_label on appliance rules.
2. nit, uid-by-position. The in-repo comment backing this is only on open Make alert severities match their definitions #249; the body names only Define alert severities in the observability docs #248 as a prerequisite.
3. nit, dashboards. "Edit in the UI, export" is a human step, and observability.md says UI editing in that folder is untested.
4. nit, references before Define alert severities in the observability docs #248. Until Define alert severities in the observability docs #248 merges, the severity line points at definitions that don't exist yet.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

Fixed in 6659a79.

1. Labels and groups.
   • The rule list now names component (central, appliance or usage).
   • It says to pick the group "whose evaluation interval and no-data handling fit; the appliance has three".
   • It says where stage comes from. On a Central rule it's the query's labels, a label template over them, or a literal for a one-stage rule. I checked: the Lambda rule uses a template and the VPN rules use "prod". Appliance rules use local.appliance_stage_label.
2. Prerequisites. The body now names Make alert severities match their definitions #249 alongside Define alert severities in the observability docs #248.
3. Dashboards. The step now reads "Edit the JSON, or export it from the UI, then run scripts/normalise-dashboard.sh".
4. Merge order. Left to merge order, which the body states. I haven't changed the PR's draft state.

I also added piri's "Skip it for changes nothing operational depends on" line.

make check passes and git diff --check is clean. This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code

[Peeja]

Claude says… plan-prod-apps failed on c3f5f79, the merge of main into this branch. This PR adds only AGENTS.md and CLAUDE.md, so nothing in it reaches that plan. The same job passed on #228, #248 and #249 against the same main, and #248's plan-dev-apps failed the same way earlier today, then passed. I can't read the job log from this session, so the cause is unknown. Re-running once.

✴️

---

Generated by Claude Code

[Peeja]

Claude reviewer says… (round on the restructure, 0bc8bb7)

This round reviewed all eight guidance PRs together; findings below are this PR's.

Approve. Only nits here, and none of the eight PRs has anything blocking or should-fix.

Verified, across all eight PRs

• git diff --check origin/main...HEAD is clean in each. In infra-central, make check passes at 0bc8bb7.
• Nothing was lost in the move. Each repo's previous section matches the new doc line by line, and every accurate sentence survives.
• Each short section still says when to act, what to add and when to skip. Each pointer names a heading that exists: "Adding a signal" in piri, ingot, delegator, swarf and piri-signing-service, and "Adding an alert or panel" on Add AGENTS.md with observability guidance #253's branch.
• Only infra-central and swarf drop a CLAUDE.md, and both had been added by the PR itself. Every other repo's existing CLAUDE.md is untouched.
• The cited paths, headings and links resolve. Each description matches its diff.

Findings for this PR

1. nit (PR body): the doc's "severity definitions above" (docs/observability.md:128) exist only once Define alert severities in the observability docs #248 merges. A trial merge of b400c5b puts them at L87–91, above the new section. The dependency was stated, but only as the last bullet under Checks.
2. nit (PR body): the "Companion PRs" line lists this PR.

✴️

---

Generated by Claude Code

[Peeja]

Claude author says…

Both fixes are in the description; there's no code change, so the head stays 0bc8bb7.

1. A "Depends on Define alert severities in the observability docs #248" line now opens the description, and the Checks bullet no longer repeats it.
2. The self-reference is gone.

This round found only nits, so there won't be another.

✴️

---

Generated by Claude Code