# HDD Skill Configuration

Use project-local configuration when the HDD workflow should reuse the same behavior across sessions.

Preferred path: `.imdone/hdd-skill.yml`

Current supported shape:

```yaml
push:
  mode: phase_prompt
  interval_minutes: 10
active_story:
  key: SCRUM-267
```

Supported keys:

- `push.mode`
  - `phase_prompt`
  - `interval_prompt`
- `push.interval_minutes`
  - positive integer minutes
  - only used when `push.mode` is `interval_prompt`
- `push.session_started_at`
  - ISO timestamp for the current HDD session baseline
  - written by `scripts/hdd_skill_state.mjs begin-session`
- `push.last_prompt_at`
  - ISO timestamp for the most recent push prompt shown to the user
  - written by `scripts/hdd_skill_state.mjs record-push-prompt`
- `push.last_push_at`
  - ISO timestamp for the most recent successful `imdone push`
  - written by `scripts/hdd_skill_state.mjs record-push-sync`
- `push.imdoneStatus`
  - current `imdone status` result collected by `scripts/hdd_skill_state.mjs get-config`
  - includes `hasPendingChanges`, which must be true before the workflow asks whether to run `imdone push`
- `active_story.key`
  - optional saved HDD story key
  - local-only resume pointer
  - should be managed through `scripts/hdd_skill_state.mjs` rather than edited inline during the HDD workflow

Smart defaults:

- `push.mode: phase_prompt`
- `push.interval_minutes: 10`

Resolution order:

1. Explicit user instruction in the current conversation
2. Stored push config in `.imdone/hdd-skill.yml`
3. Interactive setup answers when push config is missing
4. Smart defaults offered during that interactive setup

Interactive setup behavior when push config is missing:

- Treat both of these as “missing” and prompt the user:
  - `.imdone/hdd-skill.yml` does not exist
  - `.imdone/hdd-skill.yml` exists but has no `push` block yet
- `get-config` returns `push.status: "missing"` in that case and still includes the smart default values as suggested answers, not as silently accepted choices.

1. Ask whether the user wants:
   1. `Prompt after each phase (Default)`
   2. `Prompt on a timed interval`
2. If they choose the timed interval option, ask for the interval in minutes and offer `10` as the default.
3. Make it clear the user can choose the default option instead of customizing values.
4. Write the resolved values through `scripts/hdd_skill_state.mjs set-push-config` so later HDD sessions reuse the same defaults.
5. After config is stored, call `scripts/hdd_skill_state.mjs begin-session` so interval timing starts for the current HDD session.
6. Use the written config values for the current session.

Push prompt behavior:

- Before any push reminder, use `scripts/hdd_skill_state.mjs get-config` and check `push.imdoneStatus.hasPendingChanges`.
- Only ask whether to run `imdone push` when `imdone status` reports pending changes. If `imdone status` reports `Nothing to push`, do not remind the user even when the phase or interval condition is due.
- `push.promptDue` is already gated by both elapsed interval and pending `imdone status` changes.

- `phase_prompt`: ask whether to push after each completed phase, after `attachments/plan.md` is first written with a real plan, and after `Progress notes:` are added to `attachments/plan.md`, but only when `imdone status` reports pending changes.
- `interval_prompt`: call `scripts/hdd_skill_state.mjs get-config` when deciding whether the interval has elapsed and use `push.promptDue`, `push.elapsedMinutes`, and `push.nextPromptAt` instead of rough mental timing. Check this before substantive work cycles, when a major checkpoint or risk boundary is reached, and when the user explicitly asks to sync earlier. After any push reminder is shown, call `scripts/hdd_skill_state.mjs record-push-prompt` for visibility, but only call `scripts/hdd_skill_state.mjs record-push-sync` after a successful `imdone push`; the next interval is measured from the last successful push, not from the reminder itself.

When push config is missing, writing `.imdone/hdd-skill.yml` or adding the missing `push` block from the prompted setup is the expected behavior.
After push config exists, do not edit it unless the user explicitly asks for that.

Skill state helper:

```text
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs get-config
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs begin-session
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs get-active-story
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs record-push-prompt
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs record-push-sync
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs set-push-config --mode phase_prompt --interval-minutes 10
node .codex/skills/hypothesis-driven-development/scripts/hdd_skill_state.mjs set-active-story --key SCRUM-267
```

Use `get-config` when the workflow needs push reminder settings such as `phase_prompt` versus `interval_prompt`.
If `get-config` returns `push.status: "missing"`, ask the user to choose their reminder behavior before proceeding with workflow work.
Use `begin-session` after push config is available so interval timing starts from the current HDD session instead of an older run.
Use `record-push-prompt` every time the workflow actually asks whether to run `imdone push`, including early prompts caused by major checkpoints or explicit user requests. Do not call it when `imdone status` is clean and no prompt is shown.
Use `record-push-sync` only after `imdone push` succeeds; that successful sync resets the interval baseline for the next reminder.
Use `set-push-config` when interactive setup or an explicit user instruction changes push reminder behavior.
Use `get-active-story` when the workflow needs either a valid saved story with a resolved local issue path or a no-valid-story result.
