Proactive behaviors (beta)

beta:
  proactive:
    - playbook: ".charlie/playbooks/tech-debt-cleanup.md"
    - playbook: ".charlie/playbooks/sentry-triage.md"

# <Action-oriented title>

## Overview
One sentence outcome.

## Creates
- Artifact: PR | Linear issue
- Title pattern: <your preferred pattern>
- Labels: <labels>

## Limits
- Max artifacts per run: <N>
- Max diff size: <lines> lines changed
- Allowed paths: <globs>

## Data collection
- Sentry: <query>, scope, thresholds
- Repo scan: <globs>, exclusions
- GitHub checks: <criteria>

## No-op when
- <clear conditions>

## Steps
1. …
2. …

## Verify
- …

## Rollback
- …

## References
- …

# Prune dead code and unused dependencies

## Overview
Remove clearly unused files, exports, and dependencies with a small, reversible PR.

## Creates
- Artifact: PR
- Title pattern: "Proactive (beta): Prune dead code and unused deps"
- Branch: `proactive/dead-code-YYYYMMDD`
- Labels: `proactive-beta` (if available)

## Limits
- Max artifacts per run: 1 PR
- Max files changed: 20
- Max total diff: 500 changed lines
- Allowed paths: `src/**`, `packages/**`
- Excluded paths: `**/__tests__/**`, `**/__mocks__/**`, `**/fixtures/**`, `**/examples/**`, `**/docs/**`, `**/build/**`, `**/dist/**`, `**/*.d.ts`, `**/migrations/**`
- Guardrails:
  - Do not touch secrets, infra, or deployment manifests.
  - Do not remove exported symbols from a package with `"private": false` in its `package.json`; open an issue instead.

## Data collection
- Prefer analyzer output when available:
  - If the repo uses Knip: run the project’s script (e.g., `bun run knip` or `pnpm knip`) and capture: unused files, unused exports, unused deps.
  - TypeScript: enable/use compiler warnings for unused locals/params and capture results.
- Fallback heuristics (if no analyzer is present):
  - Unreferenced file candidates: files with 0 inbound references from the repo (exclude dynamic imports and entrypoints).
  - Unused export candidates: exported symbols never imported/used within the repo.
- For each candidate:
  - Verify at least two independent signals (e.g., Knip + no inbound references).
  - Ensure candidate is not an entrypoint (bin/export) nor mentioned in `exports` or `files` in `package.json`.

## No‑op when
- No candidates pass the two‑signal test, or
- The change would exceed any limit (files/lines), or
- Any candidate sits in excluded paths, or a package is public (non‑private).

## Steps
1. Create a branch `proactive/dead-code-YYYYMMDD`.
2. Build the candidate list from Data collection (respect limits/guardrails).
3. Apply removals in small commits grouped by package/area:
   - Remove dead files; update barrel exports; delete unused exports.
   - Remove unused runtime deps; keep devDeps unless clearly unused across repo tooling.
4. Run available checks (only those that exist in this repo):
   - Typecheck, lint, unit tests, knip (re‑run), and Prettier formatting.
5. If checks fail, revert the offending chunk or reduce scope until green.
6. Open a PR titled "Proactive (beta): Prune dead code and unused deps".
   - Body must include: the playbook path, a bulleted “Removals” list, analyzer excerpts, and confirmation of checks run.

## Verify
- All selected project checks pass (typecheck/lint/tests/knip when present).
- No new TypeScript unused warnings remain related to removals.

## Rollback
- Revert the PR (single revert commit). No additional cleanup required.

## References
- Internal analyzer or repo scripts (e.g., Knip).
- `package.json` `exports`/`files` fields for entrypoint validation.

# Fix README commands, links, and badges

## Overview
Bring README instructions up to date: correct commands, fix broken links/badges, and tighten quickstart steps with a minimal PR.

## Creates
- Artifact: PR
- Title pattern: "Proactive (beta): Fix README.md commands and links"
- Branch: `proactive/readme-fixes-YYYYMMDD`
- Labels: `proactive-beta` (if available)

## Limits
- Max artifacts per run: 1 PR
- Max files changed: 3 (prefer only the root `README.md`)
- Max total diff: 200 changed lines
- Allowed paths: `README.md`, `README.mdx`, `docs/**` (only if the root README references those docs)
- Guardrails:
  - Do not rewrite prose or restructure sections; only fix factual inaccuracies.
  - Do not change license text or policy statements.
  - Prefer removing broken badges vs. replacing them unless a clear, current URL is known.

## Data collection
- Scripts and commands:
  - Parse `package.json` `scripts` and check for README references to removed/renamed commands; flag mismatches.
  - Verify Node/PNPM/Bun version statements in README against `engines` (if present).
- Links and badges:
  - Validate external links and badge URLs with an HTTP HEAD/GET (3s timeout). Treat 4xx/5xx as broken.
  - For internal repo links, ensure targets exist on the default branch.
- Quickstart accuracy:
  - Compare README setup steps with the actual app/package run scripts; ensure the minimal path works.

## No‑op when
- No broken links/badges and no command mismatches, or
- Fixes would exceed limits, or
- Required authoritative targets are unclear (e.g., multiple plausible docs).

## Steps
1. Create a branch `proactive/readme-fixes-YYYYMMDD`.
2. Prepare a change list:
   - Replace or remove broken links/badges (prefer authoritative replacements).
   - Update command examples to match current scripts.
   - Align engine/version notes with `engines` if present.
3. Keep edits surgical (small diffs; avoid rewrapping large sections).
4. Run available checks:
   - Markdown/Prettier formatting, link checker if present (otherwise spot-check).
5. Open a PR titled "Proactive (beta): Fix README.md commands and links".
   - Body must include: the playbook path, a concise “Changes” list (links updated, commands corrected), and validation notes (e.g., which links were verified).

## Verify
- Links in the changed sections resolve successfully.
- Any example command runs locally in CI/dev scripts (when feasible) or is at least present in `package.json`.

## Rollback
- Revert the PR (single commit). If badges were removed, note prior URLs in the revert body for future reference.

## References
- `package.json` `scripts` and `engines`
- Internal docs referenced by README

# Triage top Sentry errors

## Overview
Review recent Sentry errors and open focused Linear issues for the highest‑impact problems with clear next steps.

## Creates
- Artifact: Linear issue(s)

## Limits
- Max artifacts per run: up to 3 issues
  - If >3 candidates meet thresholds: create 1 summary issue and include links to remaining candidates; do not open more than 3 issues total.
- Time window: last 24 hours (production)
- Guardrails:
  - Skip issues previously triaged in the last 7 days (same fingerprint).
  - Skip Sentry issues that already have a corresponding Linear issue.

## Data collection
- Sentry filter (example semantics):
  - Status: unresolved
  - Event type: error
  - Environment: production
  - Window: last 24 hours
- Ranking:
  - Sort by event count and affected users. Prefer issues with both high frequency and user impact.
- For each candidate, capture:
  - Issue title, permalink, fingerprint, event count, users affected, first/last seen, culprit, suspect commits (if available), release/version, environment.

## No‑op when
- No candidates meet thresholds (e.g., event count < 10 and users affected < 3), or
- All candidates were triaged in the past 7 days, or
- Sentry API unavailable (log and skip; do not create placeholder issues).

## Steps
1. Build candidate list using Data collection and thresholds; de‑dupe by fingerprint and recent triage history.
2. If candidates ≤ 3:
   - Create one Linear issue per candidate with:
     - Clear description (what it is, why it matters), Sentry permalink, metrics (events/users), and last seen.
     - An analysis of the likely root cause of the issue.
     - A short “Next steps” checklist (repro, owner guess, rollback plan).
3. If candidates > 3:
   - Create a single summary Linear issue with a table/list of the top N and direct permalinks, plus a triage checklist.
4. Include the playbook path in the issue(s) and note the date key for idempotency.
5. Do not close or edit existing bugs; only create new issues per the limits.

## Verify
- Each created issue contains working Sentry links and the required fields (metrics, last seen).
- No duplicate issue exists for the same fingerprint within the last 7 days.

## Rollback
- Close the created Linear issue(s) with a comment explaining the rollback and keep links for future reference.

## References
- Sentry search and ownership rules for the project(s)
- Team conventions for incident priority and assignment