---
name: augment-context
description: Use Augment local memories from Pi to gather and persist project context during coding sessions.
---

# Augment Context for Pi

Use this skill when working in a repository with the `@fingerskier/augment` Pi package installed.

## Session Start

1. Use injected Augment memory if it is already present.
2. If no injected memory appears, call `augment_project_context` with the user's task summary.
3. Read exact memories with `augment_read_memory` when search results identify likely governing context.

## Before Code Changes

1. Call `augment_search` for the file, component, command, error, or behavior being touched.
2. If work depends on a prior decision, read and follow the relevant `SPEC` or `ARCH` memory.
3. If no relevant memory exists but the task creates a durable requirement or decision, create one before implementation.

## Memory Triggers

Call `augment_upsert` whenever one of these durable events happens:

- A requirement, API contract, data model, or tool contract is clarified: use `SPEC`.
- An implementation approach, tradeoff, transport choice, persistence model, or architecture decision is made: use `ARCH`.
- A bug, risk, failing behavior, or blocker is discovered: use `ISSUE`.
- Follow-up work is intentionally deferred: use `TODO`.
- A meaningful implementation milestone is completed: use `WORK`.
- A test scenario, regression case, or verification rule is learned: use `SPEC` or `WORK`, whichever is more durable.

Call `augment_init_project` first when you need the `project_id` for `augment_upsert`.

## Links

After creating or updating a memory:

1. Use `augment_link` when a memory implements, depends on, blocks, parents, or relates to another memory.
2. Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO` they address.
3. Prefer relative memory paths for durable cross-machine identity; numeric ids are local handles.

## Session Finish

For almost every session that did real work (skip only pure Q&A, read-only inspection, or trivial mechanical ops like commit-only turns):

1. Upsert a concise `WORK` memory with what changed, key files, and verification.
2. Upsert or update `TODO` memories for known remaining work.
3. Link the final `WORK` memory to the relevant planning/decision memories.

## Guardrails

- Do not store secrets, credentials, tokens, or private keys.
- Do not store huge logs, dependency dumps, generated files, or full source files.
- Keep each memory focused; split large notes before calling `augment_upsert`.
- Treat numeric memory IDs as local handles. Relative paths are the durable identity.
- Use returned search text directly as context; do not ask Augment to summarize.
- Default to upserting when a turn did real work. When unsure, upsert.
- Do not create memories for facts already obvious from the current diff, or that duplicate an existing memory; update the existing memory instead.