Add /han-feedback skill

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "han",
       "source": "./han",
-      "description": "Meta-plugin that installs the full Han suite. Has no components of its own; it depends on han.core and han.github so installing it pulls in both.",
+      "description": "Meta-plugin that installs the bundled Han suite. Has no components of its own; it depends on han.core, han.github, and han.reporting so installing it pulls in all three. Does not bundle the opt-in han.feedback plugin.",
       "version": "3.0.0"
     },
     {
@@ -30,6 +30,12 @@
       "source": "./han.reporting",
       "description": "Reporting and summary skills for the Han suite. Turns feature specifications into plain-language stakeholder summaries (also called executive or business summaries) with diagrams, for sharing with non-technical stakeholders before implementation kicks off.",
       "version": "1.0.0"
+    },
+    {
+      "name": "han.feedback",
+      "source": "./han.feedback",
+      "description": "Post-session feedback skill for the Han suite. Captures structured observations, ratings, and improvement ideas on the Han skills you ran in a session and optionally posts them as a GitHub issue to testdouble/han. Opt-in: installed on its own, not pulled in by the han meta-plugin.",
+      "version": "1.0.0"
     }
   ]
 }

.github/ISSUE_TEMPLATE/feedback.md

@@ -0,0 +1,65 @@
+---
+name: Feedback, bug, or feature request
+about: Share feedback on a Han skill, report a bug, or request a feature
+title: ""
+labels: []
+assignees: []
+---
+
+<!--
+Thanks for taking the time to send feedback. A few notes before you post,
+adapted from the "How to provide feedback on Han" guide:
+https://github.com/testdouble/han/blob/main/docs/how-to/provide-feedback.md
+
+Be specific. "Han is great" and "Han is bad" are hard to act on. A concrete
+moment is what helps a maintainer: "the planning skill asked me about the
+database schema when the schema was right there in the code."
+
+There are two easy ways to shape feedback before you post, and both end up
+here as an issue:
+
+1. An idea, a request, or a rough "this felt off" observation.
+   Run /issue-triage in Claude Code with your note in your own words. It
+   classifies the input and lists what is missing before anyone can act on
+   it, so you can close those gaps now rather than waiting to be asked. Paste
+   the resulting triage document below as the issue body.
+
+2. Feedback on a session you ran.
+   Install the opt-in han.feedback plugin (/plugin install han.feedback@han)
+   and run /han-feedback at the end of the session, before you compact the
+   context. It summarizes what worked, what did not, and a rating, then offers
+   to post the issue for you.
+
+Prefer to write it by hand? That works too. Fill in the sections below and
+delete any that do not apply, along with these instructions.
+-->
+
+## What kind of feedback is this?
+
+<!-- Pick one: Bug · Feature request · Feedback on a skill · Question · Other -->
+
+## Which Han skill or skills does this involve?
+
+<!-- For example /code-review or /plan-a-feature. Write "not skill-specific" if it is general. -->
+
+## What happened, and what did you expect?
+
+<!--
+The concrete moment. What you saw, and what you expected instead. If this is
+a feature idea, describe the job you are trying to get done and what success
+would look like.
+-->
+
+## Anything that would help us reproduce or act on it?
+
+<!--
+For a bug: steps to reproduce, your environment (OS, Claude Code version), and
+who or what is affected. For an idea: constraints, prior art, or the direction
+you are leaning. Leave this out if nothing applies.
+-->
+
+<!--
+More detail on both paths, including how to post when you do not have the gh
+CLI installed:
+https://github.com/testdouble/han/blob/main/docs/how-to/provide-feedback.md
+-->

CLAUDE.md

@@ -1,6 +1,6 @@
 # han: Project Map
 
-Han is a Claude Code plugin suite for solo (or small-team) product engineers. It packages evidence-based planning, deep code review, investigation, and documentation workflows into deterministic slash commands that dispatch specialist sub-agents to do the judgment-heavy work. The suite ships as four plugins: `han.core` (the skills and agents), `han.github` (GitHub-facing skills), `han.reporting` (reporting and summary skills), and `han` (a meta-plugin that installs all three via dependencies).
+Han is a Claude Code plugin suite for solo (or small-team) product engineers. It packages evidence-based planning, deep code review, investigation, and documentation workflows into deterministic slash commands that dispatch specialist sub-agents to do the judgment-heavy work. The suite ships as five plugins: `han.core` (the skills and agents), `han.github` (GitHub-facing skills), `han.reporting` (reporting and summary skills), `han` (a meta-plugin that installs those three via dependencies), and `han.feedback` (an opt-in plugin carrying the post-session feedback skill, which depends on `han.core` but is deliberately *not* bundled by the `han` meta-plugin, so it is installed separately).
 
 ## Repository layout
 
@@ -11,7 +11,7 @@ Han is a Claude Code plugin suite for solo (or small-team) product engineers. It
 ├── CLAUDE.md           # This file
 ├── CHANGELOG.md        # Version history
 ├── .claude-plugin/
-│   └── marketplace.json   # Test Double marketplace manifest (lists han, han.core, han.github, han.reporting)
+│   └── marketplace.json   # Test Double marketplace manifest (lists han, han.core, han.github, han.reporting, han.feedback)
 ├── han/                # Meta-plugin: no components of its own; depends on han.core + han.github + han.reporting
 │   └── .claude-plugin/
 │       └── plugin.json
@@ -29,6 +29,10 @@ Han is a Claude Code plugin suite for solo (or small-team) product engineers. It
 │   ├── .claude-plugin/
 │   │   └── plugin.json
 │   └── skills/         # Reporting skill directories, each with SKILL.md + references/ (html-summary adds scripts/ + assets/)
+├── han.feedback/       # Opt-in feedback plugin: han-feedback (depends on han.core; NOT bundled by the han meta-plugin)
+│   ├── .claude-plugin/
+│   │   └── plugin.json
+│   └── skills/         # Feedback skill directory (han-feedback) with SKILL.md
 ├── docs/               # Operator-facing documentation
 │   ├── writing-voice.md   # Voice profile every doc follows
 │   ├── concepts.md
@@ -45,7 +49,7 @@ Han is a Claude Code plugin suite for solo (or small-team) product engineers. It
 └── images/             # Banner and graphics for README
 ```
 
-The plugins are shipped from `han.core/`, `han.github/`, and `han.reporting/`; the `han/` meta-plugin pulls in all three through its `dependencies`. Documentation lives in `docs/` and covers the whole suite. Long-form docs in `docs/skills/{name}.md` and `docs/agents/{name}.md` are the canonical operator-facing source for every skill and every agent. The underlying definition (`han.core/skills/{name}/SKILL.md`, `han.github/skills/{name}/SKILL.md`, `han.reporting/skills/{name}/SKILL.md`, or `han.core/agents/{name}.md`) is the implementation.
+The plugins are shipped from `han.core/`, `han.github/`, `han.reporting/`, and `han.feedback/`; the `han/` meta-plugin pulls in the first three (core, github, reporting) through its `dependencies`. `han.feedback` depends on `han.core` like the other layers but is deliberately left out of the meta-plugin, so it is opt-in and installed on its own. Documentation lives in `docs/` and covers the whole suite. Long-form docs in `docs/skills/{name}.md` and `docs/agents/{name}.md` are the canonical operator-facing source for every skill and every agent. The underlying definition (`han.core/skills/{name}/SKILL.md`, `han.github/skills/{name}/SKILL.md`, `han.reporting/skills/{name}/SKILL.md`, `han.feedback/skills/{name}/SKILL.md`, or `han.core/agents/{name}.md`) is the implementation.
 
 ## When to use which doc
 
@@ -63,8 +67,8 @@ The plugins are shipped from `han.core/`, `han.github/`, and `han.reporting/`; t
 
 - **[docs/concepts.md](./docs/concepts.md).** The skill-vs-agent model that runs through the whole plugin. Read once before doing anything else. Every other doc assumes this vocabulary.
 - **[docs/quickstart.md](./docs/quickstart.md).** Five path-based recipes (plan a feature, investigate a bug, review code, set up a project, research your options). Use when picking which skill to run for a specific situation. For the full end-to-end recipe for planning, bugs, or research, the quickstart points into the how-to guides below.
-- **[docs/choosing-a-han-plugin.md](./docs/choosing-a-han-plugin.md).** Which plugin to install: the full `han` suite vs. `han.core` only, the `han.github`-and-`han.reporting`-depend-on-`han.core` dependency (there is no GitHub-only or reporting-only install), and a "which one do you need?" guide. Use when an operator is at the install decision point or asks what the four plugins are.
-- **[docs/how-to/README.md](./docs/how-to/README.md).** End-to-end recipes that walk a whole workflow with specific prompts, decision points, and what to expect at each step. Two kinds live here: workflow guides for using Han (plan a feature, triage and investigate a bug, research a decision) and extension guides for building on Han ([extend Han with plugin dependencies](./docs/how-to/extend-han-with-plugin-dependencies.md), [build a plugin that depends on Han](./docs/how-to/build-a-plugin-that-depends-on-han.md)). Use when the operator wants the full recipe and not just a path-picker. The quickstart is canonical for picking a path; a how-to is canonical for running it. The two extension guides are the canonical answer to "how do I extend Han via plugin dependencies."
+- **[docs/choosing-a-han-plugin.md](./docs/choosing-a-han-plugin.md).** Which plugin to install: the bundled `han` suite vs. `han.core` only, the `han.github`-and-`han.reporting`-depend-on-`han.core` dependency (there is no GitHub-only or reporting-only install), the opt-in `han.feedback` plugin the meta-plugin does not bundle, and a "which one do you need?" guide. Use when an operator is at the install decision point or asks what the five plugins are.
+- **[docs/how-to/README.md](./docs/how-to/README.md).** End-to-end recipes that walk a whole workflow with specific prompts, decision points, and what to expect at each step. Two kinds live here: workflow guides for using Han (plan a feature, triage and investigate a bug, research a decision, provide feedback on Han) and extension guides for building on Han ([extend Han with plugin dependencies](./docs/how-to/extend-han-with-plugin-dependencies.md), [build a plugin that depends on Han](./docs/how-to/build-a-plugin-that-depends-on-han.md)). Use when the operator wants the full recipe and not just a path-picker. The quickstart is canonical for picking a path; a how-to is canonical for running it. The two extension guides are the canonical answer to "how do I extend Han via plugin dependencies."
 - **[docs/sizing.md](./docs/sizing.md).** The small / medium / large dispatch model used by the swarming skills (`/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, `/research`). Use when a swarming skill needs to decide team size, or when a user asks what `medium` / `large` mean.
 - **[docs/yagni.md](./docs/yagni.md).** The evidence-based "You Aren't Gonna Need It" rule every planning, review, and architecture skill applies before committing items to its artifact. Use when explaining why an item was deferred or rejected from a plan / review / ADR.
 - **[docs/evidence.md](./docs/evidence.md).** The three structural principles (proximity to origin, corroboration, explicit no-evidence labeling) that define what "evidence-based" means in Han, plus the trust-class vocabulary (codebase / web / provided) that grounds the corroboration gate. Use when a skill, agent, or operator asks what counts as valid evidence, how to label uncorroborated claims, or what to do when no evidence exists at all.
@@ -96,6 +100,7 @@ The plugins are shipped from `han.core/`, `han.github/`, and `han.reporting/`; t
 - **[docs/skills/update-pr-description.md](./docs/skills/update-pr-description.md).** Generate a PR description from the current branch's changes.
 - **[docs/skills/work-items-to-issues.md](./docs/skills/work-items-to-issues.md).** Publish each item in a `/plan-work-items` work-items file as a GitHub issue in its target repo, with within-repo blockers linked and no label or assignee by default.
 - **[docs/skills/runbook.md](./docs/skills/runbook.md).** Create or update a runbook for a single operational scenario (alert that has fired, incident, recurring task, known failure mode). Applies a YAGNI preflight that requires real evidence before writing.
+- **[docs/skills/han-feedback.md](./docs/skills/han-feedback.md).** Capture structured post-session feedback on Han skills and optionally post it as a GitHub issue to testdouble/han.
 
 ### Agent catalog (`docs/agents/`)
 
@@ -153,4 +158,4 @@ Folder selection rule: if the artifact is the plan, write to `docs/plans/{plan-n
 - **Every long-form doc links up.** The first bullet of the "Related Documentation" section always points back to the README at the repo root.
 - **Voice is uniform.** Every doc follows [docs/writing-voice.md](./docs/writing-voice.md). No em-dashes, direct second person, no flattery or hype.
 - **YAGNI applies to docs too.** Don't add speculative sections, for-future-flexibility warnings, or examples for behavior the skill doesn't have. The same evidence rule that gates plan steps gates docs.
-- **Indexes stay complete, not counted.** Every skill in `han.core/skills/`, `han.github/skills/`, and `han.reporting/skills/` has a long-form doc in `docs/skills/` and an entry in the skills index; same for agents in `han.core/agents/` and `docs/agents/`. Verify the indexes list every entity when editing them, rather than tracking a running total.
+- **Indexes stay complete, not counted.** Every skill in `han.core/skills/`, `han.github/skills/`, `han.reporting/skills/`, and `han.feedback/skills/` has a long-form doc in `docs/skills/` and an entry in the skills index; same for agents in `han.core/agents/` and `docs/agents/`. Verify the indexes list every entity when editing them, rather than tracking a running total.

README.md

@@ -16,15 +16,30 @@ Read [Concepts](./docs/concepts.md) for the skill-and-agent model that runs thro
 
 ## Which path are you on?
 
+### Getting started
+
 - **New to han?** → Start with [Concepts](./docs/concepts.md), then the [Quickstart](./docs/quickstart.md).
-- **Deciding which plugin to install?** → [Choosing a Han plugin](./docs/choosing-a-han-plugin.md). The full suite, core only, and the dependency that surprises people, with a quick "which one do you need?" guide.
+- **Deciding which plugin to install?** → [Choosing a Han plugin](./docs/choosing-a-han-plugin.md). The bundled suite, core only, the opt-in `han.feedback` plugin, and the dependency that surprises people, with a quick "which one do you need?" guide.
+
+### Running a workflow
+
 - **Want the end-to-end recipe for a workflow?** → [How-to guides](./docs/how-to/README.md). Plan a feature, triage and investigate a bug, or research a decision, walked through step by step.
-- **Want to extend Han with custom skills?** → [Extend Han with plugin dependencies](./docs/how-to/extend-han-with-plugin-dependencies.md) explains how one plugin builds on another through the `dependencies` field, using Han's own four-plugin split as the worked example. [Build a plugin that depends on Han](./docs/how-to/build-a-plugin-that-depends-on-han.md) is the hands-on walkthrough: stand up your own plugin, add a skill that builds on `han.core`, and confirm a clean install pulls Han in alongside it.
+- **Want to send the maintainers feedback?** → [How to provide feedback on Han](./docs/how-to/provide-feedback.md). Shape an idea or complaint into a postable issue with `/issue-triage`, or summarize a session with the opt-in `han.feedback` plugin.
+
+### Finding a skill or agent
+
 - **Looking for a specific skill?** → [Skills Index](./docs/skills/README.md). All skills grouped by purpose.
 - **Looking for a specific agent?** → [Agents Index](./docs/agents/README.md). All agents grouped by role.
+
+### Understanding how Han works
+
 - **Wondering how the agent swarms scale?** → [Sizing](./docs/sizing.md). The small / medium / large dispatch model used by `/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, and `/research`.
 - **Wondering why a skill said "YAGNI"?** → [YAGNI](./docs/yagni.md). The evidence-based rule every planning, review, and architecture skill applies before committing items to an artifact.
 - **Wondering what counts as evidence?** → [Evidence](./docs/evidence.md). The three principles (proximity, corroboration, no-evidence labeling) and the trust-class vocabulary every evidence-aware skill and agent applies.
+
+### Extending and contributing
+
+- **Want to extend Han with custom skills?** → [Extend Han with plugin dependencies](./docs/how-to/extend-han-with-plugin-dependencies.md) explains how one plugin builds on another through the `dependencies` field, using Han's own multi-plugin split as the worked example. [Build a plugin that depends on Han](./docs/how-to/build-a-plugin-that-depends-on-han.md) is the hands-on walkthrough: stand up your own plugin, add a skill that builds on `han.core`, and confirm a clean install pulls Han in alongside it.
 - **Writing or editing a skill or agent?** → [Contributing](./CONTRIBUTING.md).
 
 ## Installation
@@ -36,16 +51,19 @@ Add the Test Double skills marketplace to Claude Code, then install the plugin:
 /plugin install han@han
 ```
 
-Han ships as four plugins: 
-* `han`: a meta-plugin with no components of its own that depends on the other three
+Han ships as five plugins:
+* `han`: a meta-plugin with no components of its own that depends on `han.core`, `han.github`, and `han.reporting`
 * `han.core`: the planning, investigation, review, and documentation skills plus every agent
 * `han.github`: GitHub-facing skills like posting a code review on a PR
 * `han.reporting`: reporting skills like the stakeholder summary
-
-Installing `han@han` pulls in the whole suite, and is the right choice for almost everyone. If you do not want the
-GitHub or reporting skills, install `han.core@han` instead. There is no GitHub-only or reporting-only install: 
-both `han.github` and `han.reporting` depend on `han.core`, so installing either brings the core skills and every 
-agent along with it. For the full picture and a quick "which one do you need?" guide, 
+* `han.feedback`: an opt-in skill for capturing post-session feedback on Han skill runs
+
+Installing `han@han` pulls in the bundled suite (the meta-plugin plus `han.core`, `han.github`, and `han.reporting`),
+and is the right choice for almost everyone. If you do not want the GitHub or reporting skills, install `han.core@han`
+instead. There is no GitHub-only or reporting-only install: both `han.github` and `han.reporting` depend on `han.core`,
+so installing either brings the core skills and every agent along with it. `han.feedback` is the exception: it depends
+on `han.core` too, but the `han` meta-plugin does not pull it in, so install it separately with `han.feedback@han` if
+you want it. For the full picture and a quick "which one do you need?" guide,
 see [Choosing a Han plugin](./docs/choosing-a-han-plugin.md).
 
 ## Documentation