capture-patch-intent

name

capture-patch-intent

description

Capture and incrementally maintain durable semantic intent while implementing persistent downstream customizations, unmerged fixes, optional extensions, or experiments. Use only when the user explicitly asks to track a change as a patch, invokes this skill, or the current repository has an active Patch.md capture session for the work. Once active, keep the patch synchronized under the hood across turns and agent sessions.

Capture Patch Intent

Preserve the reason, semantic contract, and verification of a code change while implementing it. Treat patch.md as canonical intent and the code diff as one realization.

Enter capture mode

Activate only through an explicit request or an existing session record. Do not create patches for unrelated routine edits.

1. Inspect .patchmd.yaml and existing patch/session state.
2. Run patchmd begin <patch-id> --session <session-id> for a new session. Use --worktree when concurrent sessions need isolation and project initialization is committed.
3. Initialize the draft before substantial implementation.
4. For an existing patch, record its canonical revision as the proposal base; never overwrite concurrent canonical changes.

Use a stable lowercase hyphenated patch ID. Set a distinct session ID for every concurrent agent.

Maintain intent incrementally

Update the active patch.md whenever new information would change how a future agent should reimplement, verify, constrain, combine, or retire the patch.

Checkpoint after:

• User clarification or correction.
• Discovery of a material repository constraint.
• Introduction or resolution of an assumption.
• A test exposing a missing requirement.
• Selection between materially different designs.
• Changes to required behavior, invariants, non-goals, relationships, or acceptance.
• Completing a substantive implementation phase.
• Before every user-facing yield.

After synchronizing the document, run:

patchmd checkpoint --session <session-id> --summary "<material change>"

Skip document churn for formatting, local renames, repeated test runs, and other mechanical actions that do not affect durable meaning.

Separate authority levels

Record information in the appropriate section:

• Put user-stated or authoritative behavior under required behavior and explicit provenance.
• Put behavior that must not regress under invariants.
• Put excluded interpretations under non-goals.
• Put repository-derived choices under assumptions or inferred provenance.
• Put durable rationale for rejected product interpretations under decisions.
• Put consequential unknowns under open questions.

Do not turn the document into a transcript. Rewrite superseded statements so the current document is internally consistent. Do not invent motivation or constraints to make the draft look complete.

Ask only consequential questions

Use the request, conversation, repository, tests, issue context, and current diff before asking.

Ask when two reasonable interpretations would lead to materially different future behavior, compatibility, risk, composition, or retirement. Ask focused questions and do not require the user to complete a generic form or repeat known information.

Keep unresolved ambiguity visible in the draft until answered.

Implement and verify

Implement against canonical intent, not merely the draft reference diff. Keep implementation and acceptance evidence synchronized with every material clarification.

Prefer acceptance tests derived from externally observable requirements. When practical, give an independent session the acceptance-test workstream before showing it the implementation diff.

Do not mark a patch ready until:

• Required sections contain substantive content.
• Open questions explicitly contain None.
• Each required behavior has a verification method.
• reference.patch contains the verified code realization.
• Required upstream and patch checks pass or allowed exceptions are recorded.

Generate the scoped realization with patchmd reference <patch-id>. Inspect it to ensure unrelated changes were not captured. Then run patchmd validate <patch-id> --ready and patchmd ready <patch-id>.

Collaborate through proposals

Use one Git branch and preferably one worktree per session. Let each session edit its branch-local copy and checkpoint independently.

After committing an intentional session result, create a proposal:

patchmd propose --session <session-id> --summary "<semantic contribution>" \
  --evidence acceptance=passed

Do not use last-write-wins. If integration reports a stale canonical revision, compare the semantic changes and ask for adjudication when requirements, non-goals, assumptions, or acceptance contradict each other.

After Git integration, perform semantic review and rerun affected acceptance checks before treating the result as canonical.

Before yielding

Always:

1. Synchronize all material information into the session's patch proposal.
2. Run a semantic checkpoint.
3. Report unresolved questions, verification state, and whether the patch remains draft or is ready.