hdd

star 61

Hypothesis-Driven Development — treat ADRs as the source of truth, not code. Form testable hypotheses, stage ADRs, implement to test them, validate against predictions, then accept or reject based on evidence. Prevents repeated mistakes by documenting failures. Enables agent-to-agent collaboration through explicit architectural reasoning. This is the canonical HDD entry point — it replaces the thin router at .claude/commands/hdd/hdd.md.

Kastalien-Research

By Kastalien-Research schedule Updated 5/1/2026

play_arrow Run Skill in Manus View GitHub

name: hdd description: > Hypothesis-Driven Development — treat ADRs as the source of truth, not code. Form testable hypotheses, stage ADRs, implement to test them, validate against predictions, then accept or reject based on evidence. Prevents repeated mistakes by documenting failures. Enables agent-to-agent collaboration through explicit architectural reasoning. This is the canonical HDD entry point — it replaces the thin router at .claude/commands/hdd/hdd.md. argument-hint: "" [--resume] [--phases=1-2] user-invocable: true</h2> <p>Run Hypothesis-Driven Development for: $ARGUMENTS</p> <h2>Core Principle</h2> <p><strong>Code is an implementation artifact. ADRs are the source of truth.</strong></p> <p>Before writing any code, form testable hypotheses about what you expect to happen, document them in a staging ADR, implement the minimum needed to test them, validate whether reality matched predictions, then accept or reject based on evidence.</p> <h2>Inputs</h2> <p>Parse <code>$ARGUMENTS</code> for:</p> <ul> <li><code>adr_number</code> (required): The ADR number, e.g. <code>008</code></li> <li><code>title</code> (required): Brief title, e.g. <code>"Task Endpoint Implementation"</code></li> <li><code>--resume</code> (optional): Resume an existing HDD session instead of starting fresh</li> <li><code>--phases=N-M</code> (optional): Run only phases N through M. Used by <code>/workflow</code> to invoke Phases 1-2 (research + stage docs) as its Stage 2, then take back control for its own planning/implementation/review stages. Default: <code>1-5</code> (full lifecycle).</li> </ul> <h2>Phases</h2> <pre><code>Research --> Stage Docs --> Implement --> Validate --> Decide --[PR review]--> Amend | checkpoint | checkpoint | | checkpoint | checkpoint | v v v v v v hypotheses spec + ADR code + tests evidence accept/reject fix + ADR amendment </code></pre> <p>Each phase has a user checkpoint. You do NOT skip checkpoints.</p> <h3>Integration with /workflow</h3> <p>When <code>/workflow</code> dispatches to <code>/hdd</code> at Stage 2, it passes <code>--phases=1-2</code>. This produces the spec and staging ADR, then returns control to <code>/workflow</code> for its own planning, implementation, and review stages. When invoked standalone (the default), <code>/hdd</code> runs all 5 phases as a self-contained lifecycle.</p> <h2>Initialization</h2> <h3>New session (no --resume)</h3> <ol> <li><p>Check for an existing <code>.hdd/state.json</code> for this ADR number. If an active session exists, warn and ask whether to resume or start fresh.</p> </li> <li><p>Record the user-selected tracker issue/reference if one is explicitly in scope. If tracker writes are unavailable, continue with local HDD state and note the tracker gap in the handoff.</p> </li> <li><p>Create phase tasks with dependencies (Phase 2 depends on Phase 1, etc.):</p> <ul> <li>Phase 1: Research and Hypothesis Formation</li> <li>Phase 2: Stage Spec + ADR</li> <li>Phase 3: Implementation</li> <li>Phase 4: Validation</li> <li>Phase 5: Decision (Accept/Reject)</li> </ul> <p>If <code>--phases=1-2</code>, only create tasks for Phases 1 and 2.</p> </li> <li><p>Write state to <code>.hdd/state.json</code>:</p> <pre><code class="language-json">{ "workflow": "hdd", "version": "2.1", "adr_number": "<number>", "title": "<title>", "phase": "research", "phases_requested": [1, 2, 3, 4, 5], "tracker": { "provider": "<selected-tracker-or-none>", "issueId": "<optional>" }, "phaseIds": { "research": "<id>", "stage": "<id>", "implement": "<id>", "validate": "<id>", "decide": "<id>" }, "status": "in_progress", "artifacts": [], "hypotheses": [], // After Phase 1: [{ "id": "H1", "claim": "...", "prediction": "...", "validation": "...", "outcome": null }] "staging_adr_path": null, "spec_path": null, "open_risks": [], "reconciliation_flags": [], "updated_at": "<ISO timestamp>" } </code></pre> </li> <li><p>Show the session dashboard and begin Phase 1.</p> </li> </ol> <h3>Resume (--resume)</h3> <ol> <li>Read <code>.hdd/state.json</code></li> <li>Verify the local HDD state and any explicitly selected tracker reference still exist</li> <li>Show the dashboard with current state</li> <li>Resume from the current phase</li> </ol> <h2>Phase 1: Research</h2> <p><strong>Goal</strong>: Understand the problem space and form testable hypotheses.</p> <h3>Delegation</h3> <p>Dispatch one Explore-type sub-agent using the Agent tool:</p> <pre><code>Agent tool call: subagent_type: Explore prompt: | You are the HDD Research agent for ADR-${adr_number}: ${title}. ## Task Build context and form testable hypotheses for this architectural decision. ## What to read - Accepted ADRs: .adr/accepted/ (constraints and patterns) Also check docs/adr/ — legacy ADRs predate the .adr/ convention - Rejected ADRs: .adr/rejected/ (prior failure modes) Also check docs/adr/rejected/ — legacy location - Active staging: .adr/staging/ (in-flight work) - Specs: specs/ (implementation contracts) ## ADR Reconciliation For each accepted ADR related to this domain, apply these 7 signals: 1. Context mismatch — ADR describes codebase state that no longer matches 2. Broken references — files/modules mentioned have moved or been deleted 3. Dependency drift — major version change in a dependency the ADR relied on 4. Contradicting direction — this new work conflicts with the ADR's decision 5. Unrealized consequences — ADR predicted outcomes that never materialized 6. Rejected alternative resurfacing — a rejected approach is being proposed again 7. Orphaned dependency chain — ADR depends on a retired/rejected ADR If any signal fires, include it in your output with specific evidence. ## Hypotheses Form SOFT hypotheses — Specific, Observable, Falsifiable, Testable. Each hypothesis must name an exact behavior, metric, or outcome. ## Return format ``` RESEARCH SUMMARY ================ Domain: <what area of the codebase this touches> EXISTING CONSTRAINTS - <constraint from accepted ADR-NNN>: <what it means for this work> PRIOR FAILURES - <lesson from rejected ADR-NNN>: <what to avoid> RECONCILIATION FLAGS - ADR-NNN: <signal name> — <specific evidence> Recommended disposition: STILL VALID | NEEDS AMENDMENT | SUPERSEDED | INVALIDATED (or: No reconciliation flags.) HYPOTHESES H1: <specific testable claim> Prediction: <exact observable outcome> Validation: <how to test> H2: ... UNKNOWNS - <anything that blocks staging> OPEN RISKS - <anything that could derail implementation> ``` </code></pre> <p><strong>Checkpoint</strong>: Present the research summary and draft hypotheses to the user. Wait for approval before advancing.</p> <p><strong>Gate</strong>: At least one SOFT hypothesis with evidence-backed context. User approved.</p> <p><strong>Artifact persistence (MANDATORY before advancing)</strong>:</p> <p>After user approval, the orchestrator MUST:</p> <ol> <li>Write approved hypotheses to <code>.hdd/state.json</code>:<pre><code class="language-bash"># Update state.json — hypotheses array, reconciliation_flags, phase # Each hypothesis object: { "id": "H1", "claim": "...", "prediction": "...", "validation": "..." } </code></pre> </li> <li>Read <code>.hdd/state.json</code> back and verify <code>hypotheses.length > 0</code></li> <li>If verification fails, do NOT advance — fix the write and re-verify</li> </ol> <p>Phase 2 MUST refuse to start if <code>.hdd/state.json</code> has an empty hypotheses array. Conversation memory is not an artifact. If it's not on disk, it didn't happen.</p> <h3>Reconciliation Dispositions</h3> <p>When a reconciliation signal fires, the research agent recommends one of four outcomes. The orchestrator presents these to the user during the checkpoint for a decision:</p> <ol> <li><strong>STILL VALID</strong>: False positive. The ADR's reasoning holds. Note the review date and move on.</li> <li><strong>NEEDS AMENDMENT</strong>: Core decision is correct but context/reasoning needs updating to reflect current codebase. Amend the ADR in place during Phase 5 (alongside the new ADR).</li> <li><strong>SUPERSEDED</strong>: The current work replaces this ADR's decision. Move to <code>.adr/retired/</code> with a forward reference during Phase 5.</li> <li><strong>INVALIDATED</strong>: Reasoning no longer holds, no replacement exists. Move to <code>.adr/retired/</code> with an explanation. If the domain still needs a decision, the current HDD session serves as that replacement.</li> </ol> <p>Do NOT act on dispositions during Phase 1. Record them. Execute them in Phase 5 alongside the primary ADR migration.</p> <h2>Phase 2: Stage Spec + ADR</h2> <p><strong>Goal</strong>: Document WHAT we're implementing (spec) and WHY (ADR) before writing code.</p> <h3>Delegation</h3> <p>Dispatch one sub-agent:</p> <pre><code>Agent tool call: prompt: | You are the HDD Staging agent for ADR-${adr_number}: ${title}. ## Context Research summary (from Phase 1): <paste the full research output here> Approved hypotheses: <paste the user-approved hypotheses> ## Task Create two documents: ### 1. Spec (WHAT) Path: specs/${slug}.md The spec describes the implementation contract. It answers: what does the system look like after this work is done? Include: - Data structures / types being added or changed - API surface (new endpoints, tool operations, parameters) - Behavior descriptions (what happens when X) - Acceptance criteria (testable conditions for "done") Do NOT include reasoning about WHY — that belongs in the ADR. ### 2. Staging ADR (WHY) Path: .adr/staging/ADR-${adr_number}-${slug}.md Sections: - Status: Proposed - Context: Problem, current state, constraints from research - Decision: Chosen approach and why (reference alternatives considered) - Consequences: Positive outcomes, tradeoffs, follow-ups - Hypotheses: Each in SOFT format with validation plan (use format below) - Spec: Link to specs/${slug}.md - Links: Related ADRs, files, rejected approaches ### Hypothesis format in ADR ```markdown ### Hypothesis N: [Specific testable claim] Prediction: [Exact observable outcome] Validation: [Commands, observations, or measurements] Outcome: PENDING ``` ### Dependency/conflict notes If any reconciliation flags were raised in Phase 1, note them in the ADR's Context section with planned dispositions. ## Return format ``` STAGING SUMMARY =============== Spec path: specs/${slug}.md ADR path: .adr/staging/ADR-${adr_number}-${slug}.md Hypotheses staged: N Dependencies noted: [list or "none"] Conflicts noted: [list or "none"] ``` </code></pre> <p>After receiving the sub-agent output, update <code>.hdd/state.json</code> with <code>staging_adr_path</code> and <code>spec_path</code>.</p> <p><strong>Checkpoint</strong>: Present both the spec and the staging ADR to the user. Wait for approval before implementation.</p> <p><strong>Gate</strong>: Spec exists in <code>specs/</code>. Staging ADR exists in <code>.adr/staging/</code>. All sections complete. Each hypothesis is SOFT. User approved both documents.</p> <p><strong>Artifact persistence (MANDATORY before advancing)</strong>:</p> <p>After user approval, the orchestrator MUST:</p> <ol> <li>Verify the spec file exists on disk: read <code>spec_path</code> from state, then read the file</li> <li>Verify the staging ADR file exists on disk: read <code>staging_adr_path</code> from state, then read the file</li> <li>Verify <code>.hdd/state.json</code> has non-null <code>staging_adr_path</code> and <code>spec_path</code></li> <li>If any verification fails, do NOT advance — write the missing files and re-verify</li> </ol> <p>Phase 3 MUST refuse to start if either file is missing from disk.</p> <p><strong>If <code>--phases=1-2</code></strong>: Stop here. Return the spec path, ADR path, and hypotheses to the calling workflow. Update state to <code>phase: "stage-complete"</code>.</p> <h2>Phase 3: Implementation</h2> <p><strong>Goal</strong>: Build the minimum code needed to test hypotheses.</p> <h3>Delegation</h3> <p>Dispatch one or more sub-agents depending on implementation scope. For each sub-agent:</p> <pre><code>Agent tool call: prompt: | You are an HDD Implementation agent. ## Scope ADR: <paste staging ADR path and content> Spec: <paste spec path and content> ## Task Implement the minimum changes required to exercise the hypotheses in the ADR. Rules: 1. Read the spec for WHAT to build. Read the ADR for WHY. 2. Write tests tied to each hypothesis — tests validate the PREDICTION, not just that code exists. 3. Run build and type checks after implementation. 4. Track any deviation from spec with justification. 5. Do NOT commit. Changes stay uncommitted until after validation. ## Return format ``` IMPLEMENTATION SUMMARY ====================== Files modified: [list with paths] Files created: [list with paths] Tests written: N Tests passing: N/N Build: pass | fail Type check: pass | fail HYPOTHESIS COVERAGE H1: covered by test <test name> H2: covered by test <test name> ... DEVIATIONS FROM SPEC - <deviation>: <justification> (or: None.) TEST TARGETS Command: <exact test command> Files: <test file paths> ``` </code></pre> <p>After receiving summaries, update <code>.hdd/state.json</code> with artifacts and test targets.</p> <p><strong>No user checkpoint</strong> — advance directly to validation.</p> <p><strong>Gate</strong>: Implementation and hypothesis-linked tests exist. Build passes. Type checks pass.</p> <h2>Phase 4: Validation</h2> <p><strong>Goal</strong>: Test whether predictions match reality.</p> <h3>Delegation</h3> <p>Dispatch one sub-agent:</p> <pre><code>Agent tool call: prompt: | You are an HDD Validation agent. ## Context ADR: <staging ADR path and content> Test targets: <from implementation summary> ## Task For each hypothesis in the ADR: 1. Run the specific validation described in the hypothesis 2. Capture concrete evidence (test output, command output, observations) 3. Classify: VALIDATED | INVALIDATED | INCONCLUSIVE Also run full quality checks: - Build: npm run build (or equivalent) - Tests: npm test (or equivalent) - Linter: if configured - Type checker: tsc --noEmit (or equivalent) ## Return format ``` VALIDATION REPORT ================= Quality checks: build [pass|fail], tests [pass|fail], types [pass|fail] HYPOTHESIS RESULTS H1: "<claim>" Prediction: <what we expected> Evidence: <what actually happened — include command output> Classification: VALIDATED | INVALIDATED | INCONCLUSIVE Notes: <analysis of match/mismatch> H2: ... MANUAL VERIFICATION NEEDED - <hypothesis or aspect that requires human testing> (or: None — all hypotheses verified automatically.) OVERALL: ALL VALIDATED | SOME INVALIDATED | MIXED ``` </code></pre> <p><strong>Checkpoint</strong>: Present the validation report to the user. For each hypothesis, show prediction vs. evidence. Ask the user to:</p> <ol> <li>Confirm automated results</li> <li>Perform any manual testing listed</li> <li>Approve the classification of each hypothesis</li> </ol> <p><strong>Gate</strong>: Every hypothesis has an explicit outcome. User confirmed results.</p> <h2>Phase 5: Decision</h2> <p><strong>Goal</strong>: Accept or reject the ADR based on validation evidence.</p> <h3>Path A: All Hypotheses Validated</h3> <ol> <li>Update ADR status to "Accepted"</li> <li>Migrate ADR: <code>mv .adr/staging/ADR-NNN-.md .adr/accepted/</code></li> <li>Execute any reconciliation dispositions recorded in Phase 1:<ul> <li>NEEDS AMENDMENT: Edit the flagged accepted ADR in place</li> <li>SUPERSEDED: Move flagged ADR to <code>.adr/retired/</code> with forward reference</li> <li>INVALIDATED: Move flagged ADR to <code>.adr/retired/</code> with explanation</li> </ul> </li> <li>Move spec from staging if needed (spec should already be in <code>specs/</code>)</li> <li>Create the commit (ADR + spec + implementation + tests in one atomic commit):<pre><code>feat(<scope>): <description> ADR-NNN accepted — all hypotheses validated. </code></pre> </li> <li>Update the selected tracker or handoff artifact for completed HDD work</li> <li>Clean up <code>.hdd/state.json</code></li> </ol> <h3>Path B: Hypotheses Invalidated</h3> <ol> <li><strong>Do NOT commit implementation code</strong></li> <li>Document failure analysis in the ADR:<ul> <li>Which hypotheses failed and why</li> <li>What we learned</li> <li>What alternative approaches exist</li> </ul> </li> <li>Update ADR status to "Rejected (Reason: [which hypothesis])"</li> </ol> <p><strong>Checkpoint</strong>: Present the rejection analysis. The user MUST approve the rejection.</p> <ol start="4"> <li>Migrate ADR: <code>mv .adr/staging/ADR-NNN-.md .adr/rejected/</code></li> <li>Remove the staged spec: <code>trash specs/${slug}.md</code> (it describes something we didn't build)</li> <li>Rollback implementation: <code>git checkout -- <files></code></li> <li>Commit only the rejected ADR:<pre><code>docs(adr): reject ADR-NNN — [hypothesis] invalidated [Brief explanation of what was learned] </code></pre> </li> <li>Update the selected tracker or handoff artifact for completed HDD work</li> <li>Clean up <code>.hdd/state.json</code></li> </ol> <h3>Path C: Mixed Results</h3> <p>If some hypotheses validated and others didn't:</p> <ol> <li>Present the mixed results to the user</li> <li>Options: a. <strong>Accept with amendments</strong>: Update ADR and spec to reflect narrowed scope, accept b. <strong>Reject and re-scope</strong>: Reject this ADR, create a new one with revised hypotheses c. <strong>Continue validation</strong>: If inconclusive results can be resolved with more testing</li> <li>The user decides which path. Do NOT decide for them.</li> </ol> <h2>Post-Decision Review (Phase 5.5)</h2> <p><strong>Trigger</strong>: PR review (human or automated) surfaces issues after the ADR is accepted and committed. This phase is not part of the normal flow — it activates only when external review finds something Phase 4 validation missed.</p> <h3>Scope Check</h3> <p>Classify each finding before acting:</p> <table> <thead> <tr> <th>Finding Type</th> <th>Action</th> <th>Example</th> </tr> </thead> <tbody><tr> <td><strong>Hypothesis gap</strong> — a behavior the hypotheses should have tested but didn't</td> <td>Amend ADR + fix code</td> <td>"prefix-strip produces wrong internal names"</td> </tr> <tr> <td><strong>Spec gap</strong> — the spec didn't cover a mapping or edge case</td> <td>Amend ADR + update spec + fix code</td> <td>"spec lists 41 operations but mapping table has 4"</td> </tr> <tr> <td><strong>Unrelated issue</strong> — not caused by this ADR's changes</td> <td>Create a separate tracker item or handoff entry; do NOT amend this ADR</td> <td>"pre-existing bug in session handler"</td> </tr> </tbody></table> <p>If the finding is <strong>unrelated</strong>, stop here. Create a tracker item or handoff entry and move on. The rest of this phase applies only to in-scope findings.</p> <h3>Process</h3> <ol> <li><p><strong>Identify the validation gap</strong>: What hypothesis or test <em>would</em> have caught this? Name it concretely — "H7: Each <code>models_</code> gateway operation resolves to the correct internal handler name" — not "tests should be more thorough."</p> </li> <li><p><strong>Fix the code</strong>: Apply the minimum change. This is a bug fix, not a redesign.</p> </li> <li><p><strong>Amend the ADR</strong>: Add a <code>### Post-Review Amendments</code> section at the end of the accepted ADR (before Links, if present):</p> <pre><code class="language-markdown">### Post-Review Amendments #### Amendment 1: <title> (<date>) Found by: <reviewer name or tool> Finding: <one-sentence description of what was wrong> Gap: <which hypothesis should have existed or was under-specified> Fix: <what changed — file:line or commit hash> Pattern: <reusable lesson for future HDD sessions> </code></pre> </li> <li><p><strong>Update the spec</strong> if the finding reveals a spec gap (e.g., a mapping table that wasn't documented). The spec should reflect reality after the fix.</p> </li> <li><p><strong>Commit</strong>: Code fix + ADR amendment + spec update in one atomic commit:</p> <pre><code>fix(<scope>): <description> ADR-NNN post-review amendment — <gap summary>. </code></pre> </li> <li><p><strong>No new tracker epic</strong>. If the original epic is closed, reopen it with a note, or create a single fix tracker item or handoff entry. Either way, mark it complete when the fix commit lands.</p> </li> </ol> <h3>Learning Capture</h3> <p>The <code>Pattern</code> field in the amendment is the payoff. It feeds into Phase 1 research for future HDD sessions — when the research agent reads accepted ADRs, post-review amendments tell it what validation approaches failed and why.</p> <p>Common patterns to watch for:</p> <ul> <li><strong>String manipulation mappings</strong>: When operation names are derived by prefix-strip or string transform, test each mapping individually, not just the boundary.</li> <li><strong>Handler delegation chains</strong>: When the gateway delegates to a handler that has its own switch statement, verify the value that reaches the inner switch, not just that the gateway dispatched.</li> <li><strong>Type-system blind spots</strong>: When an internal API accepts <code>string</code> instead of a union type, the compiler can't catch wrong values. Test at runtime.</li> </ul> <h3>When NOT to Use Phase 5.5</h3> <ul> <li>The PR hasn't been reviewed yet — finish Phase 5 first.</li> <li>The finding requires a different architectural approach — that's a new HDD session, not an amendment.</li> <li>The finding is about code style, naming, or formatting — just fix it, no ADR amendment needed.</li> </ul> <h2>Dashboard</h2> <p>Render after every phase transition:</p> <pre><code>HDD SESSION: ADR-<number> — <title> Epic: <epicId> | Branch: <branch> Phases: <1-5 or 1-2> Phase Status Artifact ----- ------ -------- 1. Research [status] hypotheses: N, flags: N 2. Stage Docs [status] spec: specs/<slug>.md adr: .adr/staging/ADR-NNN-.md 3. Implementation [status] files: N, tests: N 4. Validation [status] validated: N, invalidated: N 5. Decision [status] accepted | rejected | pending 5.5 Post-Review [status] amendments: N (if triggered) Open risks: <count> Reconciliation: <count> flags, <count> pending dispositions </code></pre> <p>Status symbols: <code>[ ]</code> pending, <code>[~]</code> in progress, <code>[x]</code> complete, <code>[!]</code> blocked</p> <h2>Hypothesis Quality Gate</h2> <p>Before leaving Phase 1, every hypothesis MUST pass the SOFT check:</p> <ul> <li><strong>Specific</strong>: Names exact behavior, metric, or outcome — not "works correctly"</li> <li><strong>Observable</strong>: Can be verified through running code, reading output, or measuring</li> <li><strong>Falsifiable</strong>: There exists a concrete result that would prove it wrong</li> <li><strong>Testable</strong>: A test or command can exercise it within the current environment</li> </ul> <p>Reject hypotheses that are vague ("performance is good"), implementation-focused ("we will use class X"), or unfalsifiable ("code will be maintainable").</p> <h2>Operational Rules</h2> <ol> <li><strong>Orchestrator delegates</strong>: You dispatch sub-agents for each phase. You do NOT read every implementation file or write production code yourself.</li> <li><strong>Persist state after every phase</strong>: Update <code>.hdd/state.json</code> and the selected tracker or handoff artifact after each phase completes. Crashes should be recoverable. <strong>Write-then-verify</strong>: after writing state, read it back and confirm the expected data is present. Conversation memory is not an artifact — if it's not on disk, it didn't happen.</li> <li><strong>One ADR per session</strong>: Each HDD session produces exactly one ADR (accepted or rejected), plus one spec.</li> <li><strong>Atomic commits</strong>: Code changes + ADR + spec in one commit, made after validation — not during implementation.</li> <li><strong>Document failures</strong>: Rejected ADRs are as valuable as accepted ones. They prevent repeated mistakes. Rejected specs are removed (they describe unbuilt things).</li> <li><strong>Never skip checkpoints</strong>: User approval is required at Phases 1, 2, 4, and 5 (rejection only). The agent proposes; the user decides.</li> <li><strong>Conventional commits</strong>: All commits follow the format in CLAUDE.md.</li> <li><strong>Canonical entry point</strong>: This skill is THE way to run HDD. The old <code>/hdd</code> command router at <code>.claude/commands/hdd/hdd.md</code> is deprecated. The module briefs in <code>.claude/commands/hdd/modules/</code> remain as reference material for sub-agent context.</li> </ol> <h2>Anti-Patterns</h2> <ul> <li>Do NOT jump to implementation without forming hypotheses first</li> <li>Do NOT commit code before validation completes</li> <li>Do NOT write vague hypotheses to get through the gate faster</li> <li>Do NOT silently advance past a failed checkpoint</li> <li>Do NOT "fix" invalidated code — reject the ADR, learn from it, form new hypotheses</li> <li>Do NOT treat HDD as overhead — it IS the development process for architectural decisions</li> <li>Do NOT create a spec without an ADR or an ADR without a spec — they are a pair</li> <li>Do NOT treat conversation acknowledgment as artifact persistence — if hypotheses, paths, or outcomes aren't written to <code>.hdd/state.json</code> and verified by reading the file back, they will be lost when the session ends</li> </ul> <h2>When to Use HDD</h2> <p><strong>Always use for</strong>: New features, architectural changes, protocol implementations, refactoring that changes behavior, performance optimizations with measurable goals.</p> <p><strong>Skip for</strong>: Trivial bug fixes, documentation-only changes, test-only additions, formatting/linting fixes.</p> <h2>Directory Structure</h2> <pre><code>.adr/ staging/ # Work in progress — under validation accepted/ # Validated — source of truth rejected/ # Failed — documented lessons retired/ # Superseded — historical reference .hdd/ state.json # Current session state (gitignored) specs/ # Implementation specs (WHAT — paired with ADRs) </code></pre> <h2>Reference</h2> <ul> <li>Process rationale: <code>docs/WORKFLOW-MASTER-DESCRIPTION.md</code></li> <li>Module briefs: <code>.claude/commands/hdd/modules/</code> (sub-agent reference material)</li> <li>State contract: <code>.claude/commands/hdd/state.md</code></li> <li>ADR template: <code>docs/adr/000-template.md</code> (if it exists)</li> </ul> </article> </div>  <div class="w-full lg:w-80 shrink-0 flex flex-col gap-6" data-astro-cid-7zzsworf>  <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-4 shadow-sm" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-mono" data-astro-cid-7zzsworf>Install via CLI</span> <div class="flex flex-col gap-2" data-astro-cid-7zzsworf> <div id="detail-install-cmd" class="font-mono text-[11px] p-3 rounded-lg bg-black/40 border border-border select-all break-all text-primary font-bold leading-relaxed" data-astro-cid-7zzsworf> npx skills add https://github.com/Kastalien-Research/thoughtbox --skill hdd </div> <button id="detail-copy-btn" class="w-full py-2.5 rounded-lg bg-primary hover:bg-primary-hover text-on-primary font-sans font-bold text-sm shadow transition-all active:scale-95 flex items-center justify-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px]" data-astro-cid-7zzsworf>content_copy</span> <span data-astro-cid-7zzsworf>Copy Command</span> </button> </div> </div>  <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-4 shadow-sm text-on-surface" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-sans" data-astro-cid-7zzsworf>Repository Details</span> <div class="flex flex-col gap-3.5" data-astro-cid-7zzsworf> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>star</span> Stars </span> <span class="font-mono font-bold text-on-surface" data-astro-cid-7zzsworf>61</span> </div> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>call_split</span> Forks </span> <span class="font-mono font-bold text-on-surface" data-astro-cid-7zzsworf>16</span> </div> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>navigation</span> Branch </span> <span class="font-mono bg-surface border border-border px-2 py-0.5 rounded text-[11px] text-on-surface-variant" data-astro-cid-7zzsworf>main</span> </div> <div class="flex justify-between items-start text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5 mt-0.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>article</span> Path </span> <span class="font-mono bg-surface border border-border px-2 py-0.5 rounded text-[11px] text-on-surface-variant truncate max-w-[150px]" title="SKILL.md" data-astro-cid-7zzsworf>SKILL.md</span> </div> </div> </div>   <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-3 shadow-sm" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-sans" data-astro-cid-7zzsworf>More from Creator</span> <div class="flex items-center gap-2" data-astro-cid-7zzsworf> <img class="w-8 h-8 rounded-full border border-border" src="https://avatars.githubusercontent.com/u/235026280?v=4" alt="Kastalien-Research" onerror="this.src='https://avatars.githubusercontent.com/u/9919?v=4'" data-astro-cid-7zzsworf> <div class="flex flex-col min-w-0" data-astro-cid-7zzsworf> <span class="font-bold text-sm truncate text-on-surface" data-astro-cid-7zzsworf>Kastalien-Research</span> <a href="/?creator=Kastalien-Research" class="text-xs text-primary hover:underline font-semibold transition-all" data-astro-cid-7zzsworf>Explore all skills →</a> </div> </div> </div> </div> </div> </div> </div> <script> const copyBtn = document.getElementById("detail-copy-btn"); const installCmd = document.getElementById("detail-install-cmd"); if (copyBtn && installCmd) { copyBtn.addEventListener("click", () => { const cmd = installCmd.textContent.trim(); navigator.clipboard.writeText(cmd).then(() => { const originalText = copyBtn.innerHTML; copyBtn.innerHTML = ` <span class="material-symbols-outlined text-[16px]">check</span> <span>Copied!</span> `; copyBtn.style.background = "#10b981"; copyBtn.style.borderColor = "#10b981"; setTimeout(() => { copyBtn.innerHTML = originalText; copyBtn.style.background = ""; copyBtn.style.borderColor = ""; }, 1500); }); }); } </script> </div>  <footer class="border-t border-border bg-surface-container-low text-on-surface-variant py-8 px-gutter mt-16 rounded-xl"> <div class="max-w-container-max mx-auto flex flex-col md:flex-row justify-between items-center gap-6"> <div class="flex items-center gap-2"> <div class="w-6 h-6 rounded bg-primary bg-opacity-20 flex items-center justify-center"> <span class="material-symbols-outlined text-primary text-sm">code_blocks</span> </div> <span class="font-bold text-on-surface text-sm">SkillMD</span> </div> <div class="flex flex-wrap justify-center gap-6 text-sm"> <a href="/about" class="hover:text-primary transition-colors">About Us</a> <a href="/contact" class="hover:text-primary transition-colors">Contact Us</a> <a href="/privacy" class="hover:text-primary transition-colors">Privacy Policy</a> <a href="/terms" class="hover:text-primary transition-colors">Terms of Service</a> <a href="/support" class="hover:text-primary transition-colors">Support</a> </div> <div class="text-xs text-on-surface-variant/80"> © 2026 SkillMD. All rights reserved. </div> </div> </footer> </main>  <script> // Theme setup const savedTheme = localStorage.getItem("theme") || "dark"; function applyTheme(theme) { document.documentElement.classList.remove("dark", "green", "dracula", "nord"); if (theme === "dark") { document.documentElement.classList.add("dark"); } else if (theme === "green") { document.documentElement.classList.add("dark", "green"); } else if (theme === "dracula") { document.documentElement.classList.add("dark", "dracula"); } else if (theme === "nord") { document.documentElement.classList.add("dark", "nord"); } document.documentElement.setAttribute("data-theme", theme); const themeMoon = document.getElementById("theme-moon"); const themeSun = document.getElementById("theme-sun"); const themeLeaf = document.getElementById("theme-leaf"); const themeDracula = document.getElementById("theme-dracula"); const themeNord = document.getElementById("theme-nord"); if (themeMoon && themeSun && themeLeaf && themeDracula && themeNord) { themeMoon.style.display = theme === "dark" ? "inline" : "none"; themeSun.style.display = theme === "light" ? "inline" : "none"; themeLeaf.style.display = theme === "green" ? "inline" : "none"; themeDracula.style.display = theme === "dracula" ? "inline" : "none"; themeNord.style.display = theme === "nord" ? "inline" : "none"; } } applyTheme(savedTheme); const themeToggleBtn = document.getElementById("theme-toggle-btn"); if (themeToggleBtn) { themeToggleBtn.addEventListener("click", () => { const currentTheme = document.documentElement.getAttribute("data-theme") || "dark"; let newTheme = "dark"; if (currentTheme === "dark") { newTheme = "light"; } else if (currentTheme === "light") { newTheme = "green"; } else if (currentTheme === "green") { newTheme = "dracula"; } else if (currentTheme === "dracula") { newTheme = "nord"; } else { newTheme = "dark"; } applyTheme(newTheme); localStorage.setItem("theme", newTheme); }); } // Mobile menu toggle and sidebar logic const mobileMenuToggle = document.getElementById("mobile-menu-toggle"); const sidebarMenu = document.getElementById("sidebar-menu"); const sidebarOverlay = document.getElementById("sidebar-overlay"); function isMobile() { return window.innerWidth < 768; // 768px is the 'md' breakpoint in Tailwind } function openSidebar() { if (sidebarMenu) { sidebarMenu.classList.remove("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.remove("hidden"); } } function closeSidebar() { if (sidebarMenu && isMobile()) { sidebarMenu.classList.add("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } if (mobileMenuToggle && sidebarMenu) { mobileMenuToggle.addEventListener("click", (e) => { e.stopPropagation(); if (isMobile()) { const isClosed = sidebarMenu.classList.contains("-translate-x-full"); if (isClosed) { openSidebar(); } else { closeSidebar(); } } }); document.addEventListener("click", (e) => { if (isMobile()) { if (!sidebarMenu.contains(e.target) && !mobileMenuToggle.contains(e.target)) { closeSidebar(); } } }); if (sidebarOverlay) { sidebarOverlay.addEventListener("click", () => { if (isMobile()) { closeSidebar(); } }); } // Collapse sidebar when clicking a filter button, creator button, or nav item inside it sidebarMenu.addEventListener("click", (e) => { if (isMobile()) { const clickTarget = e.target.closest("button, a"); if (clickTarget) { closeSidebar(); } } }); // Sync sidebar state on window resize window.addEventListener("resize", () => { if (!isMobile()) { // Desktop: sidebar should be visible, no overlay if (sidebarMenu) { sidebarMenu.classList.remove("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } else { // Mobile: start collapsed if (sidebarMenu) { sidebarMenu.classList.add("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } }); } // If not on homepage, redirect on sidebar filter click const isHomepage = window.location.pathname === "/"; document.querySelectorAll("#occupation-filters .filter-btn").forEach(btn => { btn.addEventListener("click", (e) => { const occ = e.currentTarget.getAttribute("data-occupation"); if (!isHomepage) { window.location.href = occ ? `/?occupation=${encodeURIComponent(occ)}` : "/"; } }); }); document.querySelectorAll("#creator-filters .creator-btn").forEach(btn => { btn.addEventListener("click", (e) => { const creator = e.currentTarget.getAttribute("data-creator"); if (!isHomepage) { window.location.href = `/?creator=${encodeURIComponent(creator)}`; } }); }); </script> </body> </html>