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 and writing 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

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:

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