Raw view: Saving Workspace Context

No invisible, zero-width, or bidi-control characters detected.

---
name: saving-workspace-context
description: >-
  Persist project knowledge that should outlast this conversation: decisions,
  gotchas, research, and commands. Writes to AGENTS.md or a docs folder the
  project already uses. Use when the user asks to save or record something for
  future sessions, or at the end of a task that uncovered non-obvious facts.
user-invocable: true
disable-model-invocation: true
---

# Saving Workspace Context

Build institutional memory for a code repo without littering it. The goal is that the next agent session starts knowing what this one learned.

## Where things go

| What was learned | Where to save it |
|------------------|------------------|
| A command, path, env var name, or gotcha an agent needs every session | `AGENTS.md` (the matching section) |
| A decision with reasoning that a future reader might question | `docs/decisions/YYYY-MM-DD-<slug>.md`, or the repo's existing decisions folder |
| Research that would be painful to redo | `docs/research/<slug>.md`, or the repo's existing docs folder |
| A port, route, or integration change | `ConnectionGuide.txt` (see the shared rule) |
| A repeatable multi-step workflow | A new skill in `.agents/skills/` (ask first) |
| A convention the user keeps repeating | A repo-local rule in `.cursor/rules/` (ask first; see `suggesting-cursor-rules`) |

Prefer the harness's own memory feature for personal preferences that are not project facts.

## Rules

- **Check before creating.** Read `AGENTS.md` and the docs folder first. Update an existing entry instead of adding a parallel one.
- **Ask before creating a new top-level directory** or a new skill or rule. Small additions to existing files do not need permission; mention them in your report.
- **Never save secrets**, tokens, connection strings with credentials, or personal data.
- **Keep `AGENTS.md` short.** It loads every session. Facts, commands, and gotchas only. Long explanations go in `docs/` with a one-line pointer.
- **Date entries** in decision and research files, newest first.
- **Skip what is easily re-derived.** If the next agent can find it with one grep, do not record it.
- **Commit is the user's call.** Cloud Agents read from git, so mention that the saved file is uncommitted.

## Decision file format

```markdown
# {Decision title}

Date: {YYYY-MM-DD}
Status: accepted | superseded by {link}

## Context
{What prompted this}

## Decision
{What was chosen}

## Consequences
{What this makes easier or harder}
```

## End-of-task check

Before finishing a task, ask:

- Did I discover a command, path, or gotcha that is not in `AGENTS.md`?
- Did the user make a decision that a future reader would want the reasoning for?
- Did I do research that took more than a few minutes to reproduce?

If yes to any, save it using the table above and say what you saved.