hatch3r 1.8.0 → 2.0.0

package/skills/hatch3r-cli-stagehand/SKILL.md

@@ -1,111 +0,0 @@
----
-id: hatch3r-cli-stagehand
-description: "Browserbase Stagehand — AI-driven browser automation. Use when natural-language browser steering with on-the-fly DOM reasoning; invoke `stagehand`. Wraps Browserbase Stagehand so prompts decide which DOM nodes to inspect or click."
-tags: ["cli-tools", "browser", "opt-in"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: stagehand
-  bin: stagehand
-  tier: 3
-  category: browser
-  homepage: https://github.com/browserbase/stagehand
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# stagehand
-
-Browserbase Stagehand — AI-driven browser automation
-
-## When to Use
-
-Reach for `stagehand` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context. v3 (released 2025-10-29) operates directly on the Chrome DevTools Protocol — choose Stagehand when the target page changes shape often enough that hand-written selectors break, or when a prompt is the most compact spec of intent.
-
-## Token Cost
-
-CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
-Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
-
-## v3 Driver Model
-
-v3 dropped the hard Playwright dependency and exposes a modular driver layer. Pick the driver that matches the host environment:
-
-- **CDP-native (default):** Stagehand talks Chrome DevTools Protocol directly — no test-runner dependency, smallest install, Bun-compatible.
-- **Playwright peer:** install `playwright-core` alongside Stagehand to reuse existing Playwright fixtures, traces, or `@playwright/test` reporters.
-- **Puppeteer peer:** install `puppeteer-core` to share a launcher with existing Puppeteer scripts.
-- **Patchright peer:** install `patchright-core` for stealth-patched CDP profiles.
-
-`playwright-core`, `puppeteer-core`, and `patchright-core` are peer dependencies in v3 — install only the driver you use.
-
-## Recipes
-
-```bash
-npx create-browser-app
-```
-Scaffold a v3 Stagehand project with TypeScript wiring, a `stagehand.config.ts`, and an example `act`/`extract`/`observe` script. Replaces the v2 `npx stagehand init` workflow.
-
-```bash
-node scripts/login.ts
-```
-Execute an AI-driven action script. The script imports `Stagehand` from `@browserbasehq/stagehand`, calls `stagehand.act("click the login button")`, and Stagehand resolves the action at runtime via CDP — no test runner required.
-
-```bash
-npx browse get markdown https://example.com
-```
-One-shot page extraction via `browse-cli` (v0.6+). Returns structured Markdown the agent can consume directly; cheaper than spawning a full Stagehand session for a single read.
-
-```bash
-npx browse cdp wss://browser.example.com
-```
-Attach to an existing CDP endpoint (Browserbase managed session, local Chrome, or a custom launcher). Useful when the script delegates browser lifecycle to another supervisor.
-
-```typescript
-// scripts/observe.ts — observe primitive returns actions without executing
-import { Stagehand } from "@browserbasehq/stagehand";
-const stagehand = new Stagehand({ env: "LOCAL" });
-await stagehand.init();
-const actions = await stagehand.observe("find the login form");
-console.log(JSON.stringify(actions, null, 2));
-await stagehand.close();
-```
-Dry-run agent loop: `observe` returns the candidate action set without performing it, so a caller can route the decision (execute, ask the user, or reject).
-
-## Wrong Choice When
-
-- **High-volume scraping at scale:** Stagehand's per-action LLM round-trip is cost-prohibitive past a few hundred pages — use the Browserbase managed-browser product, raw CDP with cached locators (v3's `deepLocator`), or Stagehand's action cache once a workflow is recorded as a deterministic script.
-- **Headless CI in air-gapped environments:** Stagehand requires outbound LLM API access for selector resolution; offline environments fail the `act`/`extract`/`observe` calls. Pre-record actions with v3's automatic action cache, then replay the cached deterministic script in the air-gapped runner.
-- **Workflows already covered by a stable test suite:** if Playwright tests with hand-tuned locators already pass green, Stagehand adds an LLM round-trip per step with no behavioural gain. Use `hatch3r-cli-playwright` (tier 2) for the test surface; reserve Stagehand for the agent-driven exploratory flows.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `hatch3r-cli-playwright` (tier 2) | Existing test fixtures, deterministic CI, no LLM round-trips needed |
-| Browserbase managed browsers | Production scale, session recording, anti-bot evasion, CAPTCHA solving |
-| Stagehand action cache (built into v3) | Same workflow re-run many times — record once, replay deterministically |
-| Skyvern / Browser-Use | Workflow-style automation with embedded LLM agents and built-in task loops |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v stagehand
-```
-
-Install (mac):
-
-```bash
-# npm — v3 (Oct 29 2025); drivers are peer deps, install only what you use
-npm install -g @browserbasehq/stagehand
-# Add a driver only if you need Playwright/Puppeteer/Patchright interop:
-# npm install -g playwright-core   # OR
-# npm install -g puppeteer-core    # OR
-# npm install -g patchright-core
-```
-
-References:
-- v3 release announcement (2025-10-29): https://www.browserbase.com/blog/stagehand-v3
-- Latest npm releases: https://github.com/browserbase/stagehand/releases
-- v3 docs: https://docs.stagehand.dev/v3/get_started/introduction
-
-Homepage: https://github.com/browserbase/stagehand

package/skills/hatch3r-cli-taplo/SKILL.md

@@ -1,84 +0,0 @@
----
-id: hatch3r-cli-taplo
-description: "TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml. Use when formatting and linting pyproject.toml or Cargo.toml manifests; invoke `taplo`. Preserves YAML anchors, comments, and ordering when editing in place."
-tags: ["cli-tools", "yaml"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: taplo
-  bin: taplo
-  tier: 2
-  category: yaml
-  homepage: https://taplo.tamasfe.dev/
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# taplo
-
-TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml
-
-## When to Use
-
-Reach for `taplo` when the task is in the **yaml** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-## Token Cost
-
-CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
-Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
-
-## Recipes
-
-```bash
-taplo fmt
-```
-Format every TOML file under the cwd in-place; idempotent — safe to run in pre-commit.
-
-```bash
-taplo fmt --check
-```
-Exit non-zero if any TOML file would change; CI-friendly drift detector.
-
-```bash
-taplo lint
-```
-Surface syntax and schema-violation diagnostics; works with bundled schemas for `Cargo.toml`, `pyproject.toml`.
-
-```bash
-taplo get -f Cargo.toml package.version
-```
-Extract a single TOML value as plain stdout — replaces a multi-line `grep`/`sed` recipe.
-
-```bash
-taplo get -f pyproject.toml -o json 'project.dependencies'
-```
-Emit the value as JSON for piping into `jq` — keeps quoting unambiguous.
-
-## Wrong Choice When
-
-- The project has no TOML files (pure YAML/JSON config) — skip entirely; use `yq` for YAML, `jq` for JSON.
-- You are converting TOML to YAML/JSON as the goal — `yq` or `dasel` handle multi-format conversion in one binary.
-- The TOML lives inside a templating system (Jinja/Handlebars) — render the template first, then run `taplo` on the output.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `yq` | Mixed YAML/TOML/JSON; want a single multi-format query tool. |
-| `dasel` | Same as `yq` plus XML; cross-format updates. |
-| `grep` + `sed` | A single value lookup in a script with no `taplo` dependency available. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v taplo
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install taplo
-```
-
-Homepage: https://taplo.tamasfe.dev/

package/skills/hatch3r-cli-yq/SKILL.md

@@ -1,85 +0,0 @@
----
-id: hatch3r-cli-yq
-description: "YAML processor (mikefarah Go implementation). Use when editing Kubernetes manifests, Helm values, or GitHub-Actions workflows in place; invoke `yq`. Preserves YAML anchors, comments, and ordering when editing in place."
-tags: ["cli-tools", "yaml", "core"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: yq
-  bin: yq
-  tier: 1
-  category: yaml
-  homepage: https://github.com/mikefarah/yq
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# yq
-
-YAML processor (mikefarah Go implementation)
-
-## When to Use
-
-Reach for `yq` when the task is in the **yaml** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-## Token Cost
-
-CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
-Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
-
-## Recipes
-
-```bash
-yq '.spec.containers[].image' k8s/deployment.yml
-```
-Project every container image across multi-doc Kubernetes manifests — same path syntax as `jq`.
-
-```bash
-yq -i '.version = "1.7.5"' .agents/hatch.json
-```
-In-place edit (`-i`) — single-shot version bumps without shelling out to a templating step.
-
-```bash
-yq -o=json '.' config.yml | jq '.servers | length'
-```
-Convert YAML to JSON on the wire so `jq` can take over for richer querying.
-
-```bash
-yq eval-all '. as $i ireduce ({}; . * $i)' base.yml override.yml
-```
-Deep-merge multiple YAML documents into one — pattern for layered config (base + env override).
-
-```bash
-yq -P -i '.tags |= sort | .' content.yml
-```
-Pretty-print preservation (`-P`) keeps comments/anchors stable while sorting the `tags` array in place.
-
-## Wrong Choice When
-
-- Don't assume `yq` flags work when the binary is actually the Python `kislyuk/yq` wrapper around jq — flags and filter dialect differ. Confirm `yq --version` reports `mikefarah` first; otherwise reach for `python-yq` documentation or install the Go build.
-- Don't expect round-trip comment preservation without the `-P` (pretty) output mode; default JSON-style output drops comments. Reach for `yq -P` or `taplo` for TOML.
-- Don't use `yq` on Kubernetes manifests when you actually need schema-aware validation. Reach for `kubectl explain` / `kubeconform` and use `yq` only for projection.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `jq` (`hatch3r-cli-jq`) | JSON input, or YAML converted via `yq -o=json` — jq's filter language has more rebuild idioms. |
-| `dasel` | Multi-format (JSON/YAML/TOML/XML) single-binary path queries in CI. |
-| `taplo` | TOML-specific formatting and schema validation (`pyproject.toml`, `Cargo.toml`). |
-| `kubectl explain` | Kubernetes-resource schema lookup — `yq` projects, kubectl explains. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v yq
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install yq
-```
-
-Homepage: https://github.com/mikefarah/yq

package/skills/hatch3r-cli-zstd/SKILL.md

@@ -1,85 +0,0 @@
----
-id: hatch3r-cli-zstd
-description: "Fast lossless compression with high ratio. Use when high-ratio compression with single-digit-millisecond decompress speeds; invoke `zstd`. Designed for cold-storage payloads and CI artifact upload/download steps."
-tags: ["cli-tools", "archive", "core"]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-cli_tool:
-  id: zstd
-  bin: zstd
-  tier: 1
-  category: archive
-  homepage: https://github.com/facebook/zstd
----
-<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
-# zstd
-
-Fast lossless compression with high ratio
-
-## When to Use
-
-Reach for `zstd` when the task is in the **archive** category and the agent would otherwise call an MCP tool or read large outputs into context.
-
-## Token Cost
-
-CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
-Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
-
-## Recipes
-
-```bash
-tar --zstd -cf bundle.tar.zst dist/ governance/
-```
-Stream `tar` through zstd in one shot — default level (~3) gives high-ratio archives an order of magnitude faster than gzip.
-
-```bash
-tar --zstd -xf bundle.tar.zst -C /tmp/restore/
-```
-Extract a zstd-compressed tarball to a target directory — paired with the previous recipe for round-trip backup.
-
-```bash
-zstd -19 -T0 huge.csv
-```
-Level 19 (near-max ratio) with `-T0` (all CPU threads) — appropriate for archival snapshots where compression time is fine.
-
-```bash
-pzstd --keep -d findings.tar.zst
-```
-Parallel decompression preserving the input (`--keep`) — fastest restore path for large `.zst` archives on multi-core hosts.
-
-```bash
-zstd --train datasets/*.json -o dict.zstd && zstd -D dict.zstd payload.json
-```
-Train a dictionary from a sample corpus then compress with `-D dict.zstd` — wins when payloads share schema (logs, structured events).
-
-## Wrong Choice When
-
-- Don't use `zstd` for distribution where every byte of size matters and decompression speed does not. Reach for `xz` (`xz -9e`) — slower but tighter ratios for immutable releases.
-- Don't ship a zstd archive to legacy Windows recipients without a bundled decoder; native support landed in Windows 11 but earlier hosts need 7-Zip 21.07+. Reach for `zip` for broadest compatibility.
-- Don't reach for `zstd` to compress already-compressed payloads (JPEGs, MP4s, existing zips); ratios approach 1.0 and the CPU spend is wasted. Skip compression or use `tar -cf` with no codec.
-
-## Alternatives
-
-| Tool | When to prefer |
-|------|----------------|
-| `xz` | Immutable release artifacts where size is the dominant cost. |
-| `gzip` | Universal compatibility — every UNIX-like system since 1992. |
-| `zip` | Windows recipients without native `.zst` support; flat distribution archives. |
-| `7z` | Heterogeneous payloads where xz-style LZMA2 plus per-file streaming beats both zstd and gzip. |
-
-## Detection / Install
-
-Verify with:
-```bash
-command -v zstd
-```
-
-Install (mac):
-
-```bash
-# brew
-brew install zstd
-```
-
-Homepage: https://github.com/facebook/zstd

package/skills/hatch3r-command-customize/SKILL.md

@@ -1,23 +0,0 @@
----
-id: hatch3r-command-customize
-description: Redirect to edit orchestrator pipeline and prompt wording for slash commands under .hatch3r/commands/ -- use when changing how a command fans out to sub-agents
-tags: [customize]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-redirect_to: hatch3r-customize
----
-# Command Customization
-
-> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: command`.
-
-For command-specific reference (YAML schema, examples), see the `hatch3r-command-customize` command.
-
-## Rejected Merge Alternative (D16.3 add-vs-remove bias)
-
-Per `governance/audit/domains/D16-compound-system.md` SA 16.3, the default recommendation on functional overlap is MERGE rather than removal. Full deletion of this redirect file was rejected for two reasons:
-
-1. **Preserves UX entry points.** Users typed `/h4tcher-command-customize` or referenced the id `hatch3r-command-customize` (per `commands/hatch3r-command-customize.md:2` and sibling redirects) before consolidation. Deleting the id breaks those entry points without a redirect target.
-2. **Signals umbrella canonicality.** The `redirect_to: hatch3r-customize` frontmatter field marks `hatch3r-customize` as the single source of truth — tooling, audit scans, and adapters can resolve any redirect to the canonical without re-reading body prose.
-
-The 13-LOC redirect cost is paid once per type; the umbrella body lives in `skills/hatch3r-customize/SKILL.md`.

package/skills/hatch3r-cost-tracking/SKILL.md

@@ -1,92 +0,0 @@
----
-id: hatch3r-cost-tracking
-description: Track token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
-tags: [maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-# Cost Tracking Workflow
-
-## Quick Start
-
-```
-Task Progress:
-- [ ] Step 0: Detect ambiguity (P8 B1)
-- [ ] Step 1: Review cost tracking configuration
-- [ ] Step 2: Estimate current session token usage
-- [ ] Step 3: Identify cost optimization opportunities
-- [ ] Step 4: Generate cost report
-```
-
-## Step 0 — Detect Ambiguity (P8 B1)
-
-Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: tracking scope (session vs issue vs epic), budget values when missing from hatch.json, hardStop authority (block vs warn), report format target, and whether to defer non-critical work over budget.
-
-## Fan-out Discipline (P8 B2)
-
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
-
-## Step 1: Review Configuration
-
-1. Check `hatch.json` for a `costTracking` section.
-2. Note configured budgets: `sessionBudget`, `issueBudget`, `epicBudget`.
-3. Note warning thresholds and whether `hardStop` is enabled.
-4. If no configuration exists, operate in report-only mode.
-
-## Step 2: Estimate Token Usage
-
-Estimate tokens for the current session using these rules:
-
-| Content Type | Rule | Accuracy |
-|-------------|------|----------|
-| Messages | ~4 characters per token | High -- stable ratio for English text |
-| Tool calls | JSON length / 4 (input), response length / 4 (output) | Medium -- JSON has more overhead characters |
-| File reads | Character count / 4 | High -- but large files may be truncated by the tool |
-| Web searches | ~500 tokens per search | Low -- varies widely by result length |
-| Subagent spawns | Estimate full context re-sent per spawn (~2000-5000 tokens base) | Medium -- depends on included rules/context |
-
-**Subagent cost multiplier.** Each subagent spawn carries a base cost for the agent protocol, included rules, and context. A pipeline with 8 subagents (researcher + implementer + reviewer + fixer + 4 Phase 4 specialists) has significant overhead from context re-transmission. Factor this into budget estimates.
-
-Calculate estimated cost using the model tier rates from the `hatch3r-cost-tracking` command reference.
-
-## Step 3: Identify Optimizations
-
-Review usage patterns for savings:
-
-- **Large file reads**: Were files read multiple times without changes? Cache instead.
-- **Model tier**: Could routine tasks (linting, formatting) use a faster/cheaper model?
-- **Context bloat**: Is irrelevant context accumulating? Summarize and trim.
-- **Batching**: Were multiple small tool calls made that could be combined?
-- **Scope creep**: Did work expand beyond the original issue? Scope back.
-
-## Step 4: Generate Report
-
-Produce a cost report using the output format from the `hatch3r-cost-tracking` command. Include:
-- Total estimated tokens (input + output)
-- Estimated cost at the current model tier
-- Budget status (if configured)
-- Top optimization opportunities
-
-## Error Handling
-
-- **Token usage data unavailable**: If the platform does not expose token metrics, use input/output character counts divided by 4 as an estimate. Note the approximation method in the report.
-- **Budget limit exceeded mid-session**: Stop non-critical operations, produce a partial cost report, and recommend which remaining tasks to defer or delegate to a lower-cost model.
-- **Cost configuration missing from hatch.json**: Operate in report-only mode and note that budget enforcement is inactive. Recommend adding cost configuration to enable guardrails.
-
-## Definition of Done
-
-- [ ] Cost configuration reviewed (or report-only mode noted)
-- [ ] Token usage estimated for current session
-- [ ] Optimization opportunities identified
-- [ ] Cost report generated with budget status
-
-## Related Skills & Agents
-
-- **Command**: `hatch3r-cost-tracking` — full cost tracking protocol with guardrails and budget enforcement
-- **Skill**: `hatch3r-context-health` — context health monitoring complements cost tracking for session management

package/skills/hatch3r-incident-response/SKILL.md

@@ -1,115 +0,0 @@
----
-id: hatch3r-incident-response
-description: Handle production incidents with structured triage, mitigation, and post-mortem. Use when responding to production issues, outages, or security incidents.
-tags: [devops]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
----
-# Incident Response Workflow
-
-## Quick Start
-
-```
-Task Progress:
-- [ ] Step 0: Detect ambiguity (P8 B1)
-- [ ] Step 1: Classify severity (P0-P3) based on impact
-- [ ] Step 2: Triage — identify affected systems, user impact, blast radius
-- [ ] Step 3: Mitigate — apply hotfix or rollback, verify mitigation works
-- [ ] Step 4: Root cause analysis — trace the failure chain
-- [ ] Step 5: Write post-mortem with timeline, root cause, action items
-- [ ] Step 6: Create follow-up issues for permanent fixes and preventive measures
-```
-
-## Step 0 — Detect Ambiguity (P8 B1)
-
-Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: user-facing impact vs internal-only, blast radius known (single tenant vs all users), rollback safety verified, stakeholder notification scope (engineering vs exec vs public), and whether mitigation requires data write (irreversible) vs config flip (reversible).
-
-## Fan-out Discipline (P8 B2)
-
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
-
-## Step 1: Classify Severity
-
-| Severity | Definition                                  | Examples                                     |
-| -------- | ------------------------------------------- | -------------------------------------------- |
-| P0       | Complete outage, data loss, security breach | App unusable, auth down, data exposed        |
-| P1       | Major degradation, significant user impact  | Sync failing, billing broken, >1% error rate |
-| P2       | Partial degradation, limited impact         | Single flow broken, slow performance       |
-| P3       | Minor issue, workaround available            | Cosmetic bug, edge case                     |
-
-- Check for related issues or prior incidents using the platform tools (check `platform` in `.agents/hatch.json`):
-  - **GitHub:** Use **GitHub MCP** (`issue_read`, `search_issues`) or `gh issue list --search "..."`
-  - **Azure DevOps:** `az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS '...'"` or `az boards work-item show --id N`
-  - **GitLab:** `glab issue list --search "..."` or `glab issue view N`
-- For external library docs and current best practices, follow the project's tooling hierarchy.
-
-## Step 2: Triage
-
-- **Affected systems:** Frontend, backend, database, auth, payment, third-party services?
-- **User impact:** How many users? Which flows? Which plans (free/paid)?
-- **Blast radius:** Is the issue contained or spreading?
-- **Data:** Any data corruption, loss, or exposure? Check project privacy/security specs for implications.
-- **Timeline:** When did it start? Any recent deploys, config changes, or dependency updates?
-
-## Step 3: Mitigate
-
-- **Immediate actions:** Rollback last deploy, disable feature flag, revert config, scale up, or apply hotfix.
-- **Verification:** Confirm mitigation works — error rate drops, affected flow recovers.
-- **Communication:** Notify stakeholders if P0/P1. Document status in incident channel or issue.
-- Do not spend time on perfect fixes during active incident — stabilize first.
-
-## Step 4: Root Cause Analysis
-
-- Trace the failure chain: what changed, what failed, why.
-- Review logs (correlationId, userId), metrics, deploy history.
-- Check ADRs in project docs for architectural context.
-- For external library docs and current best practices, follow the project's tooling hierarchy.
-
-## Step 5: Post-Mortem
-
-Write a structured post-mortem document:
-
-- **Summary:** One-paragraph description of the incident.
-- **Timeline:** Key events (detection, mitigation, resolution) with timestamps.
-- **Root cause:** What went wrong and why.
-- **Impact:** Users affected, duration, business impact.
-- **Action items:** Permanent fixes, preventive measures, process improvements.
-- **Lessons learned:** What we'll do differently.
-
-Store in project incident docs or as an issue/wiki page on the platform. Follow project conventions.
-
-## Step 6: Follow-Up Issues
-
-- Create follow-up issues/work items for each action item from the post-mortem (check `platform` in `.agents/hatch.json`):
-  - **GitHub:** `gh issue create --title "..." --body "..." --label "incident-follow-up"` (or use **GitHub MCP** `issue_create`)
-  - **Azure DevOps:** `az boards work-item create --type "Bug" --title "..." --description "..." --fields "System.Tags=incident-follow-up"`
-  - **GitLab:** `glab issue create --title "..." --description "..." --label "incident-follow-up"`
-- Label appropriately (e.g., `incident-follow-up`, `P0`, `P1`).
-- Link issues/work items to the post-mortem and to each other.
-- Assign owners and due dates for critical fixes.
-
-## Error Handling
-
-- **Cannot reproduce the incident locally**: Use production logs and traces to build the timeline. If local reproduction is blocked by environment differences, document the gap and recommend a staging environment test.
-- **Mitigation introduces new issues**: Roll back the mitigation immediately, reassess the approach, and apply a more targeted fix. Document both the original incident and the mitigation regression in the post-mortem.
-- **Root cause spans multiple services or teams**: Document the cross-service dependency chain, assign follow-up items to the responsible teams, and coordinate a joint post-mortem.
-
-## Definition of Done
-
-- [ ] Incident mitigated and verified
-- [ ] Post-mortem written with timeline, root cause, and action items
-- [ ] Follow-up issues created for permanent fixes and preventive measures
-- [ ] Stakeholders notified (if P0/P1)
-- [ ] No sensitive data (secrets, PII, code content) in post-mortem or logs
-
-## Additional Resources
-
-- Privacy/security specs: project documentation
-- Observability: project logging and correlation conventions
-- Error handling: project error handling patterns