Add how-to documents covering planning, bug triage, and research workflows

[mxriverlynn]

Summary

Add a set of how-to documents to Han's docs that walk through end-to-end workflows users have built around the plugin. The content below was drafted from another project that uses Han; non-Han-specific pieces have been stripped.

These are pragmatic recipes, not skill reference docs. They show how to chain Han skills together for real work.

Open questions

• Where do these live? Candidates: extend docs/quickstart.md (which already houses path-based recipes), add a new docs/how-to/ directory, or fold into existing skill long-form docs. Decision needed before writing.
• One file or many? Three topics (planning, bugs, research) — separate files or one combined how-to doc?
• Voice and structure. Should follow docs/writing-voice.md. Likely needs index entries in docs/skills/README.md and a link from the root README.md.
• Scope creep check. Are there other how-tos worth capturing (e.g., code review loop, ADR creation, gap analysis) before we commit to a structure?

Recommend running /plan-a-feature to settle the above before drafting content.

Draft content (Han-only)

How-To: Planning Features

A planning loop using Han's planning skills, top to bottom:

1. Initial plan
   • Prompt: /plan-a-feature on building out XYZ, using {reference} as a starting point. it needs to {live here, do this, use that, etc}. write the plan to {plan file location} as we go
   • Walk through all open items and make decisions based on what Claude reports back.
2. Split into phased build (if needed)
   • Highly recommended for all but the smallest feature plans.
   • Prompt: /plan-a-phased-build {plan file location}
3. Plan phase {N} feature spec
   • Prompt: /plan-a-feature for phase {N} of {phased build doc}
   • Manually review the plan so far, prompting for adjustments if needed.
   • Walk through all open items and make decisions.
   • Prompt: /iterative-plan-review {plan file location} and watch it refute assumptions, correct inconsistencies, and surface gaps.
   • Manually review again, prompting for adjustments.
   • Walk through any remaining open items.
4. Implementation plan for phase {N}
   • Prompt: /plan-implementation {phase N feature spec file location}
   • Walk through open items and decide.
   • Prompt: /iterative-plan-review {phase N implementation plan file location}
   • Walk through any new open items.
5. Work-item breakdown for phase {N}
   • Prompt: /plan-work-items {phase N implementation plan file location} — it writes a `work-items.md` file in the plan folder.

From there, the work items are ready to be turned into issue tickets or worked directly.

How-To: Handle Bugs and Root Causes

The primary method for investigating root causes is the /investigate skill. There's also /issue-triage for documenting issues to look at later.

To find the root cause of a bug:

• Prompt: /investigate {context: this bug found here, where i saw this error, screenshot, etc}
• Tell Claude to examine relevant logs (application logs, container logs, monitoring dashboards) as appropriate for your project.
• Tell Claude to use a browser integration to view screens and see actual errors, if you have one configured.

To triage a bug for later work:

• Prompt: /issue-triage {context: this bug found here, where i saw this error, screenshot, etc}
• Tell Claude to post the report into an issue in the appropriate repository.

How-To: Research Something New

/investigate is focused on what has already happened and why. /research is focused on new information that isn't yet part of the code or process.

For example, to compare hosting options:

• Prompt: /research alternatives to {current choice}, for {purpose}, and provide a benefits and drawbacks comparison for the top 3

Once the results come back, capture the decision as an ADR:

• Prompt: /architectural-decision-record the choice of using {option}, with the other options as alternatives. we chose {option} because {reasons}

What was stripped from the source draft

For traceability — these came from the original write-up and were removed because they aren't Han skills or behaviors:

• The UI design step using pencil.dev and the gearjot.pen design file via /ui-design-from-feature-spec (not a Han skill).
• The /work-items-to-issues step plus the resulting ralph label, gh CLI auto-assignment, and blocking/blocked-by relationships (not a Han skill).
• Specific log sources (docker-compose, Render, Sentry MCPs) — generalized to "relevant logs" so the doc doesn't tie to one project's stack.
• The /chrome configuration note — generalized to "a browser integration, if you have one configured."

[mxriverlynn]

closed with #24