blast-radius-predictor: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository, following the agents.md convention. CLAUDE.md is a one-line pointer here so Claude Code picks it up — keep both in sync if you edit one.

This is a hackathon project for the Splunk AI Hackathon. We are building a predictive Blast Radius tool that pushes future-cascade impact into Splunk alert payloads at the moment they fire.

How we work

GitHub Issues are the coordination source of truth. Multiple humans and multiple agents work in this repo in parallel; all coordination happens there, not in chat logs, not in TODO comments.

Before you write code:

1. Read the design first: design_and_plan.html. It is the frozen vision — architecture diagram, the 16 sub-projects, Splunk capability map, and the demo storyboard. Open it in a browser; it is not meant to be skimmed as raw HTML.

2. Read the market analysis: blast_radius_observability_CN.md. It defines the differentiation thesis. Do not propose features that undercut "forward-propagation prediction" — that is the only defensible angle.

3. Pick an open issue. Issues are numbered #1–#16, mapped 1:1 to the sub-projects in the design. The pinned tracker is #17 — Coordination: Blast Radius Predictor; it lists everything by milestone. Filter by milestone M1 — Thin Slice first if you are running autonomously.

4. Claim it by commenting "taking this" or assigning yourself. One agent per issue at a time.

5. Respect hotspot rules. Any PR that touches:

   • src/brp/propagation/engine.py (the core algorithm — its signature is consumed by #6, #8, #11, #15)
   • src/brp/propagation/models.py (shared dataclasses)
   • splunk_app/blast_radius_predictor/default/app.conf, alert_actions.conf
   • pyproject.toml
   • AGENTS.md, README.md, PROGRESS.md, design_and_plan.html

   should carry the hotspot label. Only one open hotspot PR at a time. If one is already open, pick a different issue.

6. Work on a branch; open a PR whose description includes Closes #<issue-number>. Small, focused PRs over big ones.

7. Don't silently expand scope. If your work reveals new problems, file a new issue rather than bundling it into the current PR. Especially: do not add a new Splunk dependency, alter the propagation engine signature, or modify the alert payload schema without an issue.

8. Demo Splunk instance is shared state. Before running anything that writes to the Splunk Demo environment (Custom Alert Action installs, ITSI service writes, Detector creates), coordinate in the relevant issue so nobody else's fixtures collapse.