# Session Setup

Use this before the first workflow artifact is drafted.

## Read First

Use the story attachments as the source of truth:
- `attachments/success-metrics.md`
- `attachments/demo.md`
- `attachments/design.md`
- `attachments/plan.md`
- `attachments/diagram.md` for purpose-fit Mermaid diagrams when diagrams will reduce ambiguity; keep them in one Markdown file with clear headings
- `attachments/dod.md`
- `attachments/hdd-skill-feedback.md` if present
- `attachments/hdd-skill-feedback.json` if present
- `.imdone/hdd-skill.yml` if present

If an attachment is empty, placeholder-only, or still stock-template content, use `.imdone/templates/stock/hypothesis-driven-development.md` and the referenced partial in `.imdone/templates/stock/partials/` as fallback.

If an attachment file is missing:
- create or draft only the artifact needed for the current workflow step
- do not pre-seed later-phase attachments unless the workflow has actually reached that phase
- keep placeholder-only future-phase files out of the way unless the story already links to them and the user wants them created now

## Check Push Reminder Setup

Before resolving the story, call `scripts/hdd_skill_state.mjs get-config`.

- if `push.status` is `configured`, use the stored reminder settings for this session
- if `push.status` is `missing`, ask the user to choose their push reminder behavior using `references/configuration.md`, then persist it with `scripts/hdd_skill_state.mjs set-push-config` before continuing
- when checking whether to remind about pushing, use the `imdone status` result returned by `get-config`; only prompt when pending changes exist
- do not silently accept smart defaults when push config is missing; present them as the default option the user can choose
- after push config exists, call `scripts/hdd_skill_state.mjs begin-session` so interval timing starts from this HDD session instead of stale wall-clock time from an older run

## Resolve The Story

If an issue key is provided, open:
`backlog/current-sprint/{issueKey}-*/issue-{issueKey}.md`

If no issue key is provided:
- prefer the story already active in this conversation
- otherwise call `scripts/hdd_skill_state.mjs get-active-story` to check for one saved local HDD story
- if the helper returns a valid story path, use that story
- otherwise use the most recently modified `backlog/current-sprint/*/issue-*.md`
- confirm the candidate with the user before editing

After the story is confirmed, read the story and all relevant attachments before asking anything.
After the story is confirmed, call `scripts/hdd_skill_state.mjs set-active-story --key <issueKey>` so the next no-key HDD session can resume that story.

Detect the issue provider from the issue file metadata comment before using provider-specific language or assumptions:
- read the closing HTML comment in the issue markdown
- if it contains `jira:`, treat the story as Jira-backed
- if it contains `github:`, treat the story as GitHub-backed
- if neither marker is present, stay provider-neutral and do not invent provider-specific sync or field behavior
- use this detected provider when talking about sync, blockers, rollout notes, or evidence capture

Use the issue file as the attachment index for issue attachments:
- make sure every existing issue attachment is linked from the issue file so artifacts are easy to find
- when you create a new issue attachment, add or update an issue-file link in the same pass
- if the template already includes a link, leave it where it is
- duplicate links are acceptable when adding a missing link is simpler than normalizing existing ones
- keep links current when attachment names change or when new focused attachments are added for clarity

If the story is not already using the HDD template, use the `imdone-template` skill before continuing:
- detect this by the absence of `#HDD-template` in the issue content or by obviously missing HDD template structure
- apply template `hypothesis_driven_development` when it exists locally; otherwise apply `stock_hypothesis_driven_development`
- re-read the story and attachments after templating, then continue the HDD workflow
- explain briefly that you are switching the story onto the HDD template so the refinement artifacts land in the expected structure
- make sure `## Acceptance Criteria`, `## Vertical Slice`, `## Related Work`, `## Hypothesis`, and `## Validate Assumptions` live above `## Define the Outcome`; the checklist should only track whether those sections and attachment artifacts are complete
- make sure `Measure Results` and `Retrospect` are backed by `## Results` and `## Retrospect` sections in `attachments/success-metrics.md`; the checklist should only track completion

If the story already has `#HDD-template` but its sections, headings, or checklist order no longer match the current bundled HDD format:
- treat it as an outdated HDD story that should be repaired with the user, not ignored
- explain what is out of alignment before editing, for example missing checklist items, old heading names, or section order drift
- repair the structure first so the current skill and current story agree on what is complete vs pending
- preserve accepted content when repairing; rewrite structure and checklist state without discarding validated decisions
- after repair, continue from the next honest unchecked item instead of restarting the workflow

Extract:
- user-visible behavior that must change
- user or customer outcome that should improve
- constraints that must not change
- likely files or subsystems involved
- how completion will be verified
- which provider backs the story based on `jira:` or `github:` metadata in the HTML comment
- which checkboxes are done vs pending
- whether the story is blocked and whether the blocker reason is specific enough for another person to act on
