aim-handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# `aim-handoff`

> **MANDATE:** Execute a one-command end-of-session closeout: automatically verify and ingest any unlogged session work into `memory-wiki/` (Step 1), surgically update the standardized Engineering Handoff document (`HANDOFF.md`), commit & push both directly to `origin/main` with zero confirmation prompts, and optionally pass the baton into a fresh agent via tmux.

## Relationship to other skills

| Skill | Role |
|-------|------|
| **`aim-memory-wiki`** | **Mid-session "Save Game"** — fast (~15s) autonomous checkpoint into `memory-wiki/` without ending the session |
| **`aim-handoff`** (this) | **End-of-session closeout** — auto-includes any `memory-wiki/` delta + updates `HANDOFF.md` + pushes both to `origin/main` |
| **`aim-precompact-handoff`** | **Safeguard** — Grok context-window guard; forces a handoff *before* auto-compact destroys context |

Do not confuse precompact (when/why to write under token pressure) with this skill
(what the handoff document must look like).

---

## 0. Step 1 — Idempotent Auto-Wiki Delta Check (MANDATORY)

Before touching `HANDOFF.md`, you MUST inspect `memory-wiki/log.md`:
1. **If work or architectural decisions occurred since the last `/aim-memory-wiki`** (or `/aim-memory-wiki` was not run during this session): automatically synthesize the session's discoveries, decisions, and milestones into `memory-wiki/index.md`, `memory-wiki/log.md`, and `memory-wiki/pages/*.md` (and run `./aim index` if LanceDB is active) as Step 1 of this handoff.
2. **If `memory-wiki/` is already current for the session:** skip straight to updating `HANDOFF.md`.

---

## 1. Core philosophy

1. **UPDATE, do not decapitate.** If `HANDOFF.md` exists, you must **surgically update** it. Preserve overarching context. When told to "consolidate completed work", this means appending YOUR new accomplishments into Section 0. It is STRICTLY FORBIDDEN to delete, prune, or compress older historical entries from previous agents.
2. **Wiki first.** Long-term architecture and decisions belong in `memory-wiki/` via `aim-memory-wiki`. The handoff is the relay baton, not a second wiki.
3. **No guesses.** Unknown → write `UNKNOWN`. Proven → path, SHA, issue #, command, count.
4. **No forced architecture.** Do not invent `docs/` trees or roadmaps the Operator did not provide.
5. **Surgical Edits Required:** You MUST use surgical line-by-line file edit tools (e.g. `replace_file_content` / `edit_file`) to update the handoff. Generating the entire file from scratch (e.g. using `write_to_file` with Overwrite) is strictly forbidden as it leads to accidental data loss.

---

## 2. Gold-standard template (numbered sections)

Canonical shape: gold-standard Engineering Handoff with numbered sections **0–9**
(LeadDeed-style `HANDOFF.md` when that project uses it; otherwise `HANDOFF.md`).

When instructed to prepare a handoff, generate or **update** a structured markdown file
(e.g. `HANDOFF.md` or project-specific `HANDOFF.md`) with **all** of the following
sections. Mission-specific titles may specialize (e.g. “MODULE-BY-MODULE ANALYSIS FOR #173”)
but the **numbers and roles must remain**:

```markdown
# [Project Name] — Engineering Handoff

> **Updated:** [Timestamp]
> **Updated by:** [Session / vessel id]
> **Priority Mission:** [One-line goal]
> **Operator:** Brian Vasquez (`@BrianV1981` / `brianv1981@gmail.com` — or project-specific: `bvasquez@leaddeeds.com`, `bvasquez@ayrianna.com`, `bvasquez@skorbane.com`; never invent an email)

---

## 0. COMPLETED WORK (DO NOT REVISIT)
| Session | Work | Status |
|---------|------|--------|
| [id] | [brief] | ✅ RESOLVED |

*(Keep clean and consolidated. Point to wiki/issues for deep history — do not re-audit.)*

---

## 1. PROJECT IDENTITY
*(1–3 sentences: what the system is, prod vs local, monorepo root. Bullet key envs/URLs.)*

### Your Knowledge Base
*(Absolute paths to memory-wiki index + 3–5 critical pages/docs.)*

---

## 2. YOUR MISSION: [TITLE]
*(Overarching goal for the *incoming* session.)*

### Execution Queue (in order)
#### 1️⃣ [Task]
**Problem:** …
**Fix:** …
**Key files:** [absolute paths]

---

## 3. DETAILED ANALYSIS / BREAKDOWN
*(Mission-specific depth: module-by-module, system-by-system, or risk-ordered breakdown.
Expand freely; this is where complexity lives so §2 stays scannable.)*

---

## 4. IMPLEMENTATION STRATEGY
*(Ordered approach, tiers, pass structure, tests expected. How to attack §2/§3 without thrash.)*

---

## 5. THE CRITICAL TRAPS & WARNINGS
> **⚠️ EPISTEMIC / OPERATIONAL WARNINGS**
*(Top landmines — e.g. Vercel vs local, wrong env files, destructive git habits.)*

---

## 6. KEY PATHS
*(5–15 absolute paths grouped by concern: infra, targets of the mission, config.)*

---

## 7. THE FULL PICTURE / WHAT COMES AFTER
*(Dependency graph or short roadmap after the priority mission. Parallel quick wins table OK.)*

---

## 8. OPERATOR PREFERENCES
*(Boundaries: do/don't, proof standards, multi-agent coordination, push discipline.)*

---

## 9. IMMEDIATE NEXT STEPS
1. …
2. … *(Imperative, ordered, first command the incoming agent should run.)*
```

From BrianV1981/aim-skill-library, MIT.

More from BrianV1981/aim-skill-library