# Interaction Contract

Use this throughout the workflow.

## Operating Rules

- Draft, do not interrogate. Read context first, then propose a concrete answer.
- Be highly interactive. Human understanding is a primary outcome.
- Prefer short cycles of explain -> confirm understanding -> write.
- Keep drafts easy to scan. Prefer short paragraphs, short lists, and visible line breaks over dense walls of text.
- Ask critical questions, not just comprehension questions. Challenge weak evidence, hidden coupling, oversized slices, and unproven assumptions before writing.
- Keep the workflow anchored to user value. If a story only describes internal output, rewrite or challenge it until the user-visible or customer-visible outcome is explicit.
- Make risk explicit, but do not force artificial product-risk framing when the story is clearly enabling infrastructure.
- If a story is blocked, detect whether the blocker reason is specific enough to guide action. Treat vague blocker reasons as shared-context risk.
- If the next unchecked item depends on real-world action or evidence outside the workspace, do not fabricate progress. Record the exact evidence gate, what must happen next, and where the evidence should be captured.
- If implementation produces or updates a pull request, relate that PR back to the story and check whether the PR has enough shared context to review efficiently before treating implementation as complete.
- Before writing or revising an important artifact, make sure the human understands what is changing in plain language.
- If the user accepts something too quickly, ask one short check-back question when the artifact is important or likely to drive code changes.
- Never optimize for speed at the expense of understanding on Design, Plan, acceptance criteria, or major pivots.
- Keep everything thin and local. Prefer the smallest end-to-end slice that proves the hypothesis.
- Require measurable evidence. Push metrics toward observable behavior change, product data, and a clear measurement window rather than vague completion language.
- Require direct user evidence when confirming outcomes. If no user feedback exists yet, say so explicitly and treat the conclusion as provisional.
- Preserve clean dependency direction, but do not invent abstractions early.
- Treat `attachments/plan.md` as a live artifact. When implementation changes the path, update the plan immediately.
- When the user provides implementation feedback, decisions, corrections, or newly discovered constraints, record the resulting plan change in `attachments/plan.md` under `Progress notes:` instead of leaving that context only in chat.
- Create additional attachments when warranted for clarity and resumability, for example focused test notes, rollout notes, API notes, review context, or diagrams.
- Use this default recording pattern:
  - `Progress notes:` for what changed in execution, status, or next step
  - in the same `Progress notes:` block, include why the path changed, what feedback or constraint caused it, and what another human or AI should not have to rediscover
  - start each `Progress notes:` entry with a full ISO date-time timestamp, for example `2026-05-15T14:32:10-04:00`; do not use a date-only stamp
- Prefer the plan over a new attachment unless the context would be hard to recover from the plan alone.
- Periodically check shared-context fitness, especially after pivots, blocker discovery, PR creation, before checking Implement complete, and before closing the story.
- Keep the user in the loop when the plan changes: state what changed, why it changed, and the new next step before or while editing the plan.
- Write confirmed changes immediately. Do not batch multiple accepted items if avoidable.
- When alignment is fuzzy, load the relevant reference file and ask 1-2 pointed questions before writing.
- When presenting options of any kind, always number them explicitly (`1.`, `2.`, `3.`) so the user can reply with the number alone.
- When a checklist item is not applicable, preserve it visibly by striking through the item text rather than silently leaving it open or marking it complete.
- If an HDD-templated story is out of date relative to the current bundled format, tell the user what is misaligned and repair that structure with them before advancing the workflow item order.

## Review Loop

For each unchecked item:
1. Read the story and target attachment.
2. Draft the smallest concrete answer that fits the current context.
3. Briefly explain what the draft is trying to clarify or decide.
4. If the artifact is important enough to drive implementation, or the context still feels ambiguous, load the relevant reference file and ask 1-2 alignment, comprehension, or critical questions before finalizing the draft.
5. Present it in this shape:

*[short expert quote or framing line]*

Use the prompt line from `references/review-diff-display.md`.
List the changed file paths, then briefly summarize what changed. Rely on the tool's built-in edit diff instead of replaying a diff in chat.

Does this look right? Edit it, say yes to accept, or replace it entirely.

Formatting guidance:
- prefer 1 short paragraph or a short flat list instead of one long paragraph
- split acceptance criteria, metrics, demo steps, or sequenced behavior onto separate lines when possible
- keep critical questions short and separate from the main draft
- apply the proposed change to the real target artifact before asking for approval
- list the changed file paths so the user can open them directly in the editor
- do not replay or restate diffs in chat; rely on the tool-provided edit diff
- follow `references/review-diff-display.md` for how to present the before/after block
- if `Progress notes:` were updated in `attachments/plan.md`, say that explicitly in the user-facing message after the story footer, for example: `📝 Progress notes updated in attachments/plan.md`
- end the user-facing message with a visible indicator showing the active story key, a short story summary, and the HDD skill version from `imdone --version`. Example: `🧭 HDD v0.58.2 | SCRUM-260 — Share changelog section on prompt upgrade`

For Design, Plan, and major plan revisions, ask one short comprehension check before writing if the user has not already shown clear understanding.

If the user wants changes reverted or replaced, update the artifact and summarize the new revision. Do not paste a manual diff in chat.

## Sync Behavior

- detect the provider from the story metadata comment before using provider-specific wording; use `jira:` or `github:` markers as the source of truth
- Use `imdone pull` when the local story needs the latest provider state before continuing.
- If a sync conflict occurs during `imdone push`, resolve the file conflict, then run `imdone merge` before continuing.
- Follow `references/configuration.md` for push defaults and prompt behavior.
- Before asking whether to run `imdone push`, check `scripts/hdd_skill_state.mjs get-config` and only prompt when `push.imdoneStatus.hasPendingChanges` is true. If `imdone status` reports `Nothing to push`, skip the reminder.
- If push behavior is configured as `interval_prompt`, call `scripts/hdd_skill_state.mjs get-config` before substantial work cycles and when deciding whether to prompt, and use `push.promptDue`, `push.elapsedMinutes`, and `push.nextPromptAt` instead of rough mental timing.
- In `interval_prompt` mode, call `scripts/hdd_skill_state.mjs record-push-prompt` every time the workflow actually asks whether to run `imdone push`, including prompts triggered by elapsed time, major checkpoints, or explicit user requests.
- In `interval_prompt` mode, call `scripts/hdd_skill_state.mjs record-push-sync` only after `imdone push` succeeds. A reminder alone does not reset the interval.
- If `attachments/plan.md` is created from placeholder content into a real plan, treat that as a push-worthy checkpoint in `phase_prompt` mode.
- If `Progress notes:` are added to `attachments/plan.md`, treat that as a push-worthy checkpoint in `phase_prompt` mode because resumability context changed materially.

After each phase:
- if `push.mode` is `phase_prompt`, ask:
  `Phase complete. Push changes now? (imdone push)`
- after the first real plan is written and `push.mode` is `phase_prompt`, ask:
  `Plan updated. Push changes now? (imdone push)`
- after `Progress notes:` are added and `push.mode` is `phase_prompt`, ask:
  `Progress notes updated. Push changes now? (imdone push)`
- if `push.mode` is `interval_prompt` and `push.promptDue` is true, ask:
  `Phase complete and the push interval has elapsed. Push changes now? (imdone push)`
- if `push.mode` is `interval_prompt` and `push.promptDue` is false, do not ask to push yet; if `imdone status` is clean, say nothing about pushing

If the user says yes, run `imdone push`, then call `scripts/hdd_skill_state.mjs record-push-sync`. If no, leave the interval overdue state intact and remind the user to push before ending the session.
