handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# Handoff

Produce a professional Feature Completion Summary from the current session's git history and conversation context. The output is a markdown file saved to `docs/handoffs/YYYY-MM-DD-feature-name.md` that the next session (or another agent) can read to resume work without replaying the entire conversation.

Data sources in priority order:
1. **Git log** — `git log --oneline -20` (commit history)
2. **Git diff** — `git diff --stat HEAD~N` (changed files)
3. **Conversation context** — what the agent remembers from this session
4. **Test results** — `python -m pytest tests -q --tb=no` (final pass/fail count)

## Output Format

Write the output file to `docs/handoffs/YYYY-MM-DD-feature-name.md`. Create `docs/handoffs/` if it doesn't exist. Use this template:

```markdown
---
type: handoff
session: [feature-name]
date: [YYYY-MM-DD]
status: GREEN | RED
next_task: [single next technical task, 5-8 words]
---

# Session Summary — [Feature Name]

## Commits

[Numbered list of commits on the working branch, newest first.
 Include short hash + message for each.]

## Files Modified/Created

[Bold each file path; one-line description of what changed.]

## Verification

[Exact command the next agent should run to confirm the repository is green before starting work.]

```bash
python -m pytest tests -q --tb=no
```

[Expected output: X passed, Y failed.]

## Global Status

Ran full test suite: X passed, Y failed, Z warnings.
Global status: GREEN | RED

## Architectural Decisions

[Bullet list of key decisions with the choice, rationale, AND the alternative considered.
 Format:
 - **Decision**: [what was decided]
   **Why**: [rationale, trade-offs, constraints]
   **Alternative**: [the rejected option and why it was rejected]
]

## Locked ADRs

[Explicit list of ADRs that govern this architecture. No deviations permitted without a new ADR.]

- ADR-0001: [title] — [one-sentence scope]
- ADR-0002: [title] — [one-sentence scope]

## Frontier

[The single next technical task for the next session.
 Be specific enough that the next agent can start without context.
 Include file paths, function names, and the expected approach.]

## Blockers (if any)

[Things that are stuck, why, and what would unblock them.]

## Agent Re-hydration Block

[3-sentence paragraph. Copy-paste this into a brand-new chat session to instantly restore context.]

I am starting a new session. Load the `handoff` skill and read `docs/handoffs/YYYY-MM-DD-feature-name.md` to understand the current state and the Frontier, then begin the next task on the list. Before making any changes, run `python -m pytest tests -q --tb=no` to confirm the repository is GREEN.
```

## Workflow

### 1. Gather Evidence

Run in parallel where possible:

- `git log --oneline -20` — recent commits on current branch
- `git diff --stat HEAD~1` — changed files in the latest commit (or HEAD~N for N commits)
- `git status --short` — any uncommitted changes
- `python -m pytest tests -q --tb=no` — final test count

If the session spans multiple branches, run `git branch --show-current` first.

### 2. Extract Architectural Decisions

Scan the conversation context for moments where a trade-off was made and a specific choice was locked. Look for:

- "We decided X instead of Y because..."
- "The trade-off is..."  
- "The alternative considered was..."
- Explicit "Decision" markers from ADRs or grilling sessions

For each decision, explicitly name the **Alternative Considered** and why it was rejected. This prevents the next agent from re-suggesting the rejected option.

Aim for 3-5 decisions per session.

### 3. Identify Locked ADRs

Scan the conversation and `docs/adr/` directory for ADR files. List every ADR that governs the area being handed off. The "Locked ADRs" section makes it explicit to the next agent: "These decisions are frozen. Do not deviate without a new ADR."

### 4. Identify the Frontier

The frontier is the single next concrete task. It must name:

- The file to modify (or create)
- The function or class to implement
- The expected approach (one sentence)

From ThorStarlord/interface-skills, MIT.

More from ThorStarlord/interface-skills