83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
|
---
|
||
|
|
name: emergency-procedures
|
||
|
|
description: >
|
||
|
|
Recovery protocols when development loops fail, agent context is corrupted, git state is tangled,
|
||
|
|
or quality gates break. Use when development becomes chaotic, thrashing loops occur, or when asked to recover state.
|
||
|
|
concerns: [system-one-balance]
|
||
|
|
---
|
||
|
|
|
||
|
|
# Emergency Recovery Procedures
|
||
|
|
|
||
|
|
Standardized protocols for halting cascading failures, stabilizing git state, restoring agent context, and recovering working development branches.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 0: Setup and Protocols
|
||
|
|
|
||
|
|
1. **Circuit-Breaker Invariants**:
|
||
|
|
- **Halt Implementation**: When an agent gets stuck in a thrashing loop, stop writing additional code immediately.
|
||
|
|
- **Zero Destructive Discards**: Never run destructive commands (`git reset --hard`, `git clean -fdx`) without creating a safe backup branch or stash first.
|
||
|
|
- **Isolate the Failure**: Determine whether the defect is environment, git state, code regression, or context divergence.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 1: Ingest and Check
|
||
|
|
|
||
|
|
1. Detect emergency signals:
|
||
|
|
- **Context Loss**: Agent suggests solutions contradicting established repo patterns or attempts wide, unsolicited rewrites.
|
||
|
|
- **Git Confusion**: Unmerged conflicts, detached HEAD state, or untracked changes scattered across directories.
|
||
|
|
- **Test Thrashing**: Attempted fixes repeatedly break tests in alternating cycles.
|
||
|
|
2. Freeze and document:
|
||
|
|
- Record the current git commit SHA, active branch, and modified file list (`git status`).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 2: Processing (Core Logic)
|
||
|
|
|
||
|
|
### Step 1: Secure Working State
|
||
|
|
Before making any changes, preserve the current uncommitted state:
|
||
|
|
```bash
|
||
|
|
# Create a safety branch with current WIP
|
||
|
|
git checkout -b emergency-backup-$(date +%Y%m%d%H%M%S)
|
||
|
|
git add -A
|
||
|
|
git commit -m "emergency: snapshot before recovery"
|
||
|
|
```
|
||
|
|
|
||
|
|
### Step 2: Roll Back to Last Known Good State
|
||
|
|
Return to the main branch or stable checkpoint:
|
||
|
|
```bash
|
||
|
|
git checkout -
|
||
|
|
git status
|
||
|
|
```
|
||
|
|
|
||
|
|
### Step 3: Re-anchor Context
|
||
|
|
1. Inspect the last stable commit and review actual working patterns in the codebase.
|
||
|
|
2. Read project README, architecture docs, or `SPEC.md` to re-align goals.
|
||
|
|
3. Formulate the single smallest task that can be verified in isolation.
|
||
|
|
|
||
|
|
### Step 4: Decompose Complex Tasks
|
||
|
|
If a task ballooned in complexity:
|
||
|
|
1. Break down the task into steps of ≤ 50 lines of change each.
|
||
|
|
2. Sequence steps so each can be independently tested and committed.
|
||
|
|
3. Obtain user confirmation on the refined task plan before re-attempting.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 3: The System One Balance Pass
|
||
|
|
|
||
|
|
- **Augment, Don't Handcuff**:
|
||
|
|
- Do NOT panic or spam long conversational apologies. State the issue concisely, show the preserved backup branch, and propose the recovery plan.
|
||
|
|
- Safe inspection (`git status`, `git diff`, `git log`) must be executed immediately without confirmation gates.
|
||
|
|
- Reserve confirmation prompts strictly for discarding branches or rolling back production databases.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 4: Output Execution & Verification
|
||
|
|
|
||
|
|
1. Verify:
|
||
|
|
- Workspace working tree is clean or returned to a stable, reproducible state.
|
||
|
|
- Test suite passes on the recovered base.
|
||
|
|
2. Deliver the incident summary:
|
||
|
|
- Root cause of the disruption.
|
||
|
|
- State of the backup branch.
|
||
|
|
- Concrete, small next step to resume forward progress safely.
|