# Is Capture

> Write something down so it is not lost — a decision, a finding, a piece of context worth keeping. Use when someone says write this down, note this, save this, keep this somewhere, don't let me forget, remember this, put this in my notes, or add this to the knowledge base; or when a decision has just been made that would be expensive to relitigate. Not for saving an ordinary source or config file — that is a plain file write.

- Skill: `ideaspaces-xyz/is-capture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ideaspaces-xyz/is-capture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ideaspaces-xyz/is-capture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: IdeaSpaces-xyz (https://skillmd.com/u/ideaspaces-xyz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ideaspaces-xyz/is-capture

---


# Capture

Capture is the agreement moment: conversation becomes shared state.

Do not make the user or agent choose between `write`, `is_write`, `git add`, and `is_commit` at the top level. The intent is **capture**. This skill chooses the mechanism.

Canonical protocols: read [capture](../../reference/capture.md) and [writing](../../reference/writing.md) when the task needs the full capture and writing standards.

## When to Propose

- **Decision made.** "We're going with X because Y." Highest-value capture — prevents relitigating.
- **Understanding shifted.** Something got articulated that wasn't clear before.
- **Research produced a finding.** Took effort to produce, would take effort to reproduce.
- **Pattern emerged.** Same thing surfaced three times — the common thread is worth naming.
- **Context that saves time.** Next session would need this to be productive.

**Don't propose** when it's already in code/git, is a temporary task detail, is a personal preference, or the conversation is still forming.

## Mechanism Choice

| Situation | Use |
|---|---|
| New or updated knowledge Note | `is_write` — it creates frontmatter, stages, tracks, and returns `sha` |
| Purpose / Now / Note-style markdown refinement | `is_write` with safe-update `sha` |
| Existing spec/doc/README/agent contract edit | native `edit` / `write`, then `is_commit` with explicit paths |
| File move/delete | native `bash` (`git mv`, `rm`), then `is_commit` with explicit paths |
| User asks to share/push after capture | `is-push` / `is_push` |

`is_write` is a capture primitive, not the outer intent. Reach for it inside this skill when the target is a Note that should carry Layer 1 frontmatter (`name`, `summary`) and optional Layer 2 fields (`tags`, `attached_to`). Use native edits for README/spec/docs and `_agent/` primitives that are not Note-style files; still end at the same capture boundary with `is_commit` unless the user explicitly wants local draft state.

### Derived local Map inspection

When the user asks to map a repository, or a durable navigation frame may be worth curating, inspect the candidate territory through the installed CLI rather than rebuilding a walker:

```bash
is_cli() {
  if [ -n "$IS_CLI_PATH" ] && [ -f "$IS_CLI_PATH" ]; then
    case "$IS_CLI_PATH" in
      *.js) node "$IS_CLI_PATH" "$@" ;;
      *) "$IS_CLI_PATH" "$@" ;;
    esac
  else
    ideaspaces "$@"
  fi
}
is_cli map <repo> --depth full --json
```

This is an offline working-tree observation, not an automatic capture. Review `portable`, `dirty`, and `local_only_paths`; selection still needs agreement. Numeric depth remains bounded to 1–4, and `full` is explicit enumeration rather than ambient orientation.

## How

Two arrivals, different consent. A local commit is one revert from undone — narration beats
permission at this tier.

**The user asked** — "save this", "write that down", "note this", or ran `/is-commit`. The ask IS
the agreement: write, commit, and narrate in one line ("Saved the auth decision to the space.").
Never answer a save request with "shall I commit?" — that is asking permission for permission.

**You noticed a boundary** — a decision just landed, a milestone wrapped, the session is closing
meaningful work. Offer once, lightly:

> "That decision about [X] is worth capturing. Want me to write it to the space?"

If the user says no, drop it and don't re-ask. **Mid-flow with neither signal: stay silent** —
keep working; captures settle at boundaries, not per thought.

Either way, the mechanics:

1. Search first (`bash` with `find`/`rg`) to avoid duplicates; `read` the target area for context.
2. Choose the mechanism:
   - Note capture or Note-style refinement → `is_write`.
   - Existing README/doc/spec/contract refinement → native `edit` / `write`.
   - Moves/deletes → `bash` (`git mv`, `rm`).
3. For `is_write` refinements, use safe updates:
   - first update to an existing file: `is_status({ path })` → use returned `sha` as `if_match`
   - refinement of a file just written: use the prior `is_write` response `sha`
   - `force: true` only after re-reading and reconciling divergent content
4. Show what changed when useful.
5. Commit with `is_commit({ message, all: true })` for paths captured by this Pi session, or explicit `paths` for confirmed native edits. Never adopt unrelated staged work.
6. Say what was saved. Optionally use **is-push** / `is_push` to share with the remote (or **is-pull** first to get the latest).
7. Cleanup is separate from capture and is owned by `pi-local-context`. After a meaningful capture or any natural boundary where context is cluttered, offer a cleanup preview and use the `context-cleanup` skill / `context_cleanup` tool if it appears in your available tools. If `context_cleanup` is not available, skip the cleanup offer.

## Commit message

Use the space's commit convention when present (for example `_agent/skills/commit.md`) — it defines the message shape and the provenance trailers. Don't restate the trailer format here.

## Rhythm

One or two captures per meaningful session. Not every session produces one.

After meaningful captures, check: does Now still match? → **is-reflect**