From 554f6c56d3a3d4181dbad9ebcab2ab00ba935a81 Mon Sep 17 00:00:00 2001 From: Tamika Nomara Date: Tue, 28 Jul 2026 19:31:37 +0400 Subject: [PATCH] chore(lint): make Markdown Prettier-safe and re-enable it PR #127 took Markdown out of Prettier's scope because running it corrupted files that agents read as raw source. Two of Prettier's normalizations are core CommonMark rules that cannot be turned off (ordered-list renumbering and inline-code-span trimming), and a fenced block also closes early when a ```markdown example embeds its own nested fence. The fix is to make the source robust to these rather than configure them away. With that done, Prettier formats this repo's Markdown without changing what any file says. Config: - .prettierrc.json: proseWrap "preserve" (no paragraph reflow, so the reformat stays small) and embeddedLanguageFormatting "off" (leave fenced code alone). - .prettierignore: stop excluding *.md; ignore the schematic html-template.html that Prettier hard-errors on. - .pre-commit-config.yaml: update the stale comment that said Markdown is excluded. Cosmetic reformat (proseWrap preserve keeps it small): table-column re-alignment in README, docs/{evidence,readability,sizing,yagni}, skill-description-frontmatter, and han-research/research, plus a list-continuation indent fix in code-overview-to-confluence. Source made robust to the un-disable-able normalizations. An earlier repo-wide `prettier --write` (ab708a7) had already applied some of these to Markdown while it was still in scope, and later v5 authoring added new unsafe constructs; an audit of both surfaced four files that still render wrong or would be corrupted: - project-documentation, plan-a-feature: an ordered list that a lead-in sentence (or a "5a." sub-marker) interrupts had collapsed into a run-on paragraph; give each item a valid start on its own line so it renders as a list again. - overview-template, writing-effective-instructions: the ```markdown template examples embed a nested fence, so wrap each in a 4-backtick outer fence and the inner fence no longer closes the outer block early. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ --- .pre-commit-config.yaml | 12 +++--- .prettierignore | 19 +++++---- .prettierrc.json | 4 +- README.md | 28 ++++++------- docs/evidence.md | 30 +++++++------- docs/readability.md | 40 +++++++++---------- docs/sizing.md | 8 ++-- docs/yagni.md | 38 +++++++++--------- .../skills/code-overview-to-confluence.md | 2 +- .../references/overview-template.md | 9 ++--- .../skills/project-documentation/SKILL.md | 28 +++++++------ han-planning/skills/plan-a-feature/SKILL.md | 29 +++++++------- .../skill-description-frontmatter.md | 24 +++++------ .../writing-effective-instructions.md | 7 ++-- han-research/skills/research/SKILL.md | 8 ++-- 15 files changed, 148 insertions(+), 138 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1dc3c8a2..4ac9b734 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -6,11 +6,13 @@ exclude: "^(docs/plans/|docs/research/|han-reporting/skills/html-summary/assets/)" repos: - # Prettier owns formatting for JSON, YAML, and JS at 120 columns. Markdown is - # deliberately excluded in .prettierignore: agents read skills and reference - # files as raw source, and Prettier's list renumbering and code-span trimming - # change what those files say. Running the local devDependency keeps Prettier's - # version in package.json only, not duplicated in a hook mirror. + # Prettier owns formatting for Markdown, JSON, YAML, and JS at 120 columns. + # Markdown runs with proseWrap: preserve and embeddedLanguageFormatting off (see + # .prettierrc.json). Agents read skills and reference files as raw source, so the + # source is kept robust to the two normalizations Prettier cannot turn off — + # ordered-list renumbering and inline code-span trimming — and Prettier then + # leaves what those files say unchanged. Running the local devDependency keeps + # Prettier's version in package.json only, not duplicated in a hook mirror. # It runs first so the hygiene fixers below never fight it. - repo: local hooks: diff --git a/.prettierignore b/.prettierignore index efc971f2..b4fd2f4d 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,14 +1,12 @@ # Markdown is the product, not just prose about it: skills, agents, and reference # files are read as raw source by agents, so a transform that renders the same can # still change what an agent is told to do. Prettier has two such transforms that -# cannot be turned off, because they are core CommonMark normalizations: -# * It renumbers ordered lists, while the prose cross-references to those steps -# ("see Step 6") stay put and end up pointing at the wrong ones. -# * It strips the spaces inside inline code spans, so a heading spec written as -# ` — ` becomes `—` next to prose that still says "with surrounding spaces". -# Both survive proseWrap: preserve and embeddedLanguageFormatting: off, so there is -# no configuration that formats this repo's Markdown without corrupting it. -*.md +# cannot be turned off, because they are core CommonMark normalizations: it +# renumbers ordered lists, and it strips the padding spaces inside inline code +# spans. The source is kept robust to both (ordered lists are already sequential, +# and no prose wraps a padded spec like ` — ` in backticks), so proseWrap: preserve +# plus embeddedLanguageFormatting: off formats this repo's Markdown without +# corrupting it. Keep it that way when editing. # Static historical artifacts: left as written. docs/plans/ @@ -17,6 +15,11 @@ docs/research/ # Vendored third-party assets: checked in verbatim, never reformat. han-reporting/skills/html-summary/assets/ +# A schematic HTML sketch, not real HTML: Prettier hard-errors trying to parse it. +# The prek hook never hands it over (it filters to markdown, JSON, YAML, and JS), +# but ignore it here too so a direct `prettier .` stays green. +han-reporting/skills/html-summary/references/html-template.html + # Dependencies and generated files. node_modules/ package-lock.json diff --git a/.prettierrc.json b/.prettierrc.json index 963354f2..60face34 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,3 +1,5 @@ { - "printWidth": 120 + "printWidth": 120, + "proseWrap": "preserve", + "embeddedLanguageFormatting": "off" } diff --git a/README.md b/README.md index 6f33378d..0fab46c1 100644 --- a/README.md +++ b/README.md @@ -41,21 +41,21 @@ Add the Test Double skills marketplace to Claude Code, then install the plugin: Han ships as multiple plugins: -| Plugin | Type | What it brings | -| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Plugin | Type | What it brings | +| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`han`** | parent | the parent plugin that brings in `han-communication`, `han-core`, `han-documentation`, `han-research`, `han-planning`, `han-coding`, `han-github`, and `han-reporting` | -| `han-communication` | bundled | the foundational plugin beneath every other: the shared readability standard and writing-voice profile, plus the skills and agent that apply them | -| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, and the canonical rule files | -| `han-documentation` | bundled | documentation skills: project docs, architectural decision records, and runbooks | -| `han-research` | bundled | pre-planning knowledge-work skills: research, gap analysis, and issue triage, plus the research-analyst agent | -| `han-planning` | bundled | planning skills you reach for before implementation | -| `han-coding` | bundled | coding skills you reach for while working in code | -| `han-github` | bundled | GitHub-facing skills like posting a code review on a PR | -| `han-reporting` | bundled | reporting skills like the stakeholder summary | -| `han-feedback` | opt-in | skill for capturing post-session feedback on Han skill runs | -| `han-atlassian` | opt-in | skills for publishing docs and work items to Atlassian products | -| `han-linear` | opt-in | skill for publishing work items to Linear (requires a Linear MCP server) | -| `han-plugin-builder` | opt-in | carries the guidance and skills for building your own skills, agents, and plugins | +| `han-communication` | bundled | the foundational plugin beneath every other: the shared readability standard and writing-voice profile, plus the skills and agent that apply them | +| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, and the canonical rule files | +| `han-documentation` | bundled | documentation skills: project docs, architectural decision records, and runbooks | +| `han-research` | bundled | pre-planning knowledge-work skills: research, gap analysis, and issue triage, plus the research-analyst agent | +| `han-planning` | bundled | planning skills you reach for before implementation | +| `han-coding` | bundled | coding skills you reach for while working in code | +| `han-github` | bundled | GitHub-facing skills like posting a code review on a PR | +| `han-reporting` | bundled | reporting skills like the stakeholder summary | +| `han-feedback` | opt-in | skill for capturing post-session feedback on Han skill runs | +| `han-atlassian` | opt-in | skills for publishing docs and work items to Atlassian products | +| `han-linear` | opt-in | skill for publishing work items to Linear (requires a Linear MCP server) | +| `han-plugin-builder` | opt-in | carries the guidance and skills for building your own skills, agents, and plugins | Installing `han@han` pulls in the bundled suite (the meta-plugin plus `han-communication`, `han-core`, `han-documentation`, `han-research`, `han-planning`, `han-coding`, `han-github`, and `han-reporting`), and is the right diff --git a/docs/evidence.md b/docs/evidence.md index 65d64064..6ad059eb 100644 --- a/docs/evidence.md +++ b/docs/evidence.md @@ -134,23 +134,23 @@ extracts them so other skills and agents can apply the same vocabulary. Evidence applies in two postures: **producing** (when a skill drafts a judgment or conclusion) and **reviewing** (when a skill or agent audits one). -| Surface | What evidence-based gates | -| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`/research`](../han-research/docs/skills/research.md) | The canonical home of the trust classes, the corroboration gate, and the no-evidence label. Strict mode requires every claim driving the recommendation to carry an explicit evidence status. | -| [`/investigate`](../han-coding/docs/skills/investigate.md) | Investigation findings cite the file path, log line, or measurement that supports them. The corroboration gate applies when the investigation draws on web sources for context; codebase findings stand on their citation. | -| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Behaviors, edge cases, and coordinations in the spec carry evidence. Items without evidence move to `## Deferred (YAGNI)`; items with evidence flagged as single-source web claims get marked accordingly. | -| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation choices cite evidence per the YAGNI rule. When a recommendation rests on web research, the corroboration gate applies. | -| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Review pillars include the evidence sweep alongside YAGNI. Uncited claims and single-source web claims surface as findings. | -| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Each gap cites the artifact it rests on; the evidence-based-investigator verifies against current state with file-level evidence. | -| [`/code-review`](../han-coding/docs/skills/code-review.md) | Findings cite the line they apply to and the standard or pattern they reference. | -| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified when the project does the thing the standard governs today. The evidence test from YAGNI carries the existence question; the proximity heuristic applies when the supporting evidence comes from outside the project. | +| Surface | What evidence-based gates | +| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`/research`](../han-research/docs/skills/research.md) | The canonical home of the trust classes, the corroboration gate, and the no-evidence label. Strict mode requires every claim driving the recommendation to carry an explicit evidence status. | +| [`/investigate`](../han-coding/docs/skills/investigate.md) | Investigation findings cite the file path, log line, or measurement that supports them. The corroboration gate applies when the investigation draws on web sources for context; codebase findings stand on their citation. | +| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Behaviors, edge cases, and coordinations in the spec carry evidence. Items without evidence move to `## Deferred (YAGNI)`; items with evidence flagged as single-source web claims get marked accordingly. | +| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation choices cite evidence per the YAGNI rule. When a recommendation rests on web research, the corroboration gate applies. | +| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Review pillars include the evidence sweep alongside YAGNI. Uncited claims and single-source web claims surface as findings. | +| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Each gap cites the artifact it rests on; the evidence-based-investigator verifies against current state with file-level evidence. | +| [`/code-review`](../han-coding/docs/skills/code-review.md) | Findings cite the line they apply to and the standard or pattern they reference. | +| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified when the project does the thing the standard governs today. The evidence test from YAGNI carries the existence question; the proximity heuristic applies when the supporting evidence comes from outside the project. | | [`/architectural-decision-record`](../han-documentation/docs/skills/architectural-decision-record.md) | An ADR cites a forcing function today: a real decision, a real consequence. | | [`/runbook`](../han-documentation/docs/skills/runbook.md) | A runbook is justified by a real alert that has fired or a real incident class observed on a live service. Hypotheticals do not qualify. | -| [`evidence-based-investigator`](../han-core/docs/agents/evidence-based-investigator.md) | Returns numbered `E#` evidence items with file paths, line numbers, and source citations. Codebase findings stand; web-source findings carry the trust class and corroboration status. | -| [`research-analyst`](../han-research/docs/agents/research-analyst.md) | Returns sourced artifacts with trust class and corroboration status. Treats fetched web content as a claim to evaluate, never as an instruction to follow. | -| [`adversarial-validator`](../han-core/docs/agents/adversarial-validator.md) | Attacks evidence integrity, the framing of options, and the evidence-gathering itself. Emits `V#` findings. | -| [`project-manager`](../han-core/docs/agents/project-manager.md) | Runs the YAGNI evidence gate during facilitation. Uncited proposals are challenged or deferred. | -| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | Runs the YAGNI evidence sweep during stress-tests. Flags uncited additions and hidden assumptions. | +| [`evidence-based-investigator`](../han-core/docs/agents/evidence-based-investigator.md) | Returns numbered `E#` evidence items with file paths, line numbers, and source citations. Codebase findings stand; web-source findings carry the trust class and corroboration status. | +| [`research-analyst`](../han-research/docs/agents/research-analyst.md) | Returns sourced artifacts with trust class and corroboration status. Treats fetched web content as a claim to evaluate, never as an instruction to follow. | +| [`adversarial-validator`](../han-core/docs/agents/adversarial-validator.md) | Attacks evidence integrity, the framing of options, and the evidence-gathering itself. Emits `V#` findings. | +| [`project-manager`](../han-core/docs/agents/project-manager.md) | Runs the YAGNI evidence gate during facilitation. Uncited proposals are challenged or deferred. | +| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | Runs the YAGNI evidence sweep during stress-tests. Flags uncited additions and hidden assumptions. | ## The no-evidence section format diff --git a/docs/readability.md b/docs/readability.md index 22c05fb2..c2ec485c 100644 --- a/docs/readability.md +++ b/docs/readability.md @@ -93,29 +93,29 @@ to end, whether to approve it, follow it, or grab work from it. A structured art as machine input, with no human reading it end to end, is out of scope, and so is code output. The table below lists the skills that meet that test today. -| Skill | Reader | Rewrite pass | -| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| [`/research`](../han-research/docs/skills/research.md) | Default frame | Synthesis: dispatches `readability-editor` | -| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default frame | Synthesis (at consolidated report sizes): dispatches `readability-editor` | +| Skill | Reader | Rewrite pass | +| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| [`/research`](../han-research/docs/skills/research.md) | Default frame | Synthesis: dispatches `readability-editor` | +| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default frame | Synthesis (at consolidated report sizes): dispatches `readability-editor` | | [`/project-documentation`](../han-documentation/docs/skills/project-documentation.md) | A technically-literate reader who needs to understand the feature before reading its code | Synthesis: dispatches `readability-editor` | -| [`/issue-triage`](../han-research/docs/skills/issue-triage.md) | Default frame | Self-check only | +| [`/issue-triage`](../han-research/docs/skills/issue-triage.md) | Default frame | Self-check only | | [`/runbook`](../han-documentation/docs/skills/runbook.md) | Default frame | Self-check only | | [`/architectural-decision-record`](../han-documentation/docs/skills/architectural-decision-record.md) | Default frame | Self-check only | -| [`/code-overview`](../han-coding/docs/skills/code-overview.md) | Default frame | Synthesis: dispatches `readability-editor` | -| [`/investigate`](../han-coding/docs/skills/investigate.md) | The engineer who will implement the fix and may be paged on the bug | Synthesis: dispatches `readability-editor` | -| [`/code-review`](../han-coding/docs/skills/code-review.md) | The author and reviewers of the change under review | Synthesis: dispatches `readability-editor` | -| [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) | The engineer weighing the module's design | Synthesis: dispatches `readability-editor` | -| [`/stakeholder-summary`](../han-reporting/docs/skills/stakeholder-summary.md) | The non-technical stakeholder | Synthesis: dispatches `readability-editor` | -| [`/html-summary`](../han-reporting/docs/skills/html-summary.md) | The non-technical stakeholder | Self-check only (prose content; visual layout keeps its own conventions) | -| [`/update-pr-description`](../han-github/docs/skills/update-pr-description.md) | The reviewer evaluating the pull request, who will read the code | Synthesis: dispatches `readability-editor` | -| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | The stakeholder or reviewer who reads the spec | Synthesis: dispatches `readability-editor` | -| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | The engineer who will build the feature | Synthesis: dispatches `readability-editor` | -| [`/plan-a-phased-build`](../han-planning/docs/skills/plan-a-phased-build.md) | The reader of the phased build (mixed engineering / product by default) | Synthesis: dispatches `readability-editor` | -| [`/plan-work-items`](../han-planning/docs/skills/plan-work-items.md) | The engineer who grabs a work item and implements it | Self-check only | -| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | The reader of the plan the review refines | Self-check only | -| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | The engineer who must follow the standard | Synthesis: dispatches `readability-editor` | -| [`/automated-test-planning`](../han-coding/docs/skills/automated-test-planning.md) | The engineer who will implement the tests | Synthesis: dispatches `readability-editor` | -| [`/manual-test-planning`](../han-coding/docs/skills/manual-test-planning.md) | The person who runs the tests by hand, who may not be technical | Synthesis: dispatches `readability-editor` | +| [`/code-overview`](../han-coding/docs/skills/code-overview.md) | Default frame | Synthesis: dispatches `readability-editor` | +| [`/investigate`](../han-coding/docs/skills/investigate.md) | The engineer who will implement the fix and may be paged on the bug | Synthesis: dispatches `readability-editor` | +| [`/code-review`](../han-coding/docs/skills/code-review.md) | The author and reviewers of the change under review | Synthesis: dispatches `readability-editor` | +| [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) | The engineer weighing the module's design | Synthesis: dispatches `readability-editor` | +| [`/stakeholder-summary`](../han-reporting/docs/skills/stakeholder-summary.md) | The non-technical stakeholder | Synthesis: dispatches `readability-editor` | +| [`/html-summary`](../han-reporting/docs/skills/html-summary.md) | The non-technical stakeholder | Self-check only (prose content; visual layout keeps its own conventions) | +| [`/update-pr-description`](../han-github/docs/skills/update-pr-description.md) | The reviewer evaluating the pull request, who will read the code | Synthesis: dispatches `readability-editor` | +| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | The stakeholder or reviewer who reads the spec | Synthesis: dispatches `readability-editor` | +| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | The engineer who will build the feature | Synthesis: dispatches `readability-editor` | +| [`/plan-a-phased-build`](../han-planning/docs/skills/plan-a-phased-build.md) | The reader of the phased build (mixed engineering / product by default) | Synthesis: dispatches `readability-editor` | +| [`/plan-work-items`](../han-planning/docs/skills/plan-work-items.md) | The engineer who grabs a work item and implements it | Self-check only | +| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | The reader of the plan the review refines | Self-check only | +| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | The engineer who must follow the standard | Synthesis: dispatches `readability-editor` | +| [`/automated-test-planning`](../han-coding/docs/skills/automated-test-planning.md) | The engineer who will implement the tests | Synthesis: dispatches `readability-editor` | +| [`/manual-test-planning`](../han-coding/docs/skills/manual-test-planning.md) | The person who runs the tests by hand, who may not be technical | Synthesis: dispatches `readability-editor` | This list is authoritative. A contributor adding a new skill applies the inclusion test above and, if it passes, wires the standard in (see [Contributing](../CONTRIBUTING.md#wiring-the-readability-standard-into-a-skill)). diff --git a/docs/sizing.md b/docs/sizing.md index 431b3382..32a8d408 100644 --- a/docs/sizing.md +++ b/docs/sizing.md @@ -104,16 +104,16 @@ When the size is overridden with `$size`: ## Sizing across skills at a glance -| Skill | What gets sized | Small | Medium | Large | -| -------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Skill | What gets sized | Small | Medium | Large | +| -------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [`/architectural-analysis`](../han-coding/docs/skills/architectural-analysis.md) | Signal-selected roster + finding calibration | Single module, no cross-cutting signal (spine + concurrency, 3–4 agents) | One cross-cutting concern (spine + 1–2 specialists, 4–6 agents) | Multi-subsystem or cross-service seam (spine + all signalled specialists + system-architect, 6–9 agents) | | [`/code-overview`](../han-coding/docs/skills/code-overview.md) | Exploration roster (codebase-explorer only) | Single file, symbol, or small change set (1 explorer) | A directory/module or moderate change set (2–3 explorers) | Multiple subsystems or a large change set (3–5 explorers) | | [`/code-review`](../han-coding/docs/skills/code-review.md) | Agent roster + finding calibration | 1–3 files, single subsystem | 3–10 files, one cross-cutting concern | More than 10 files, multiple subsystems | -| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default-on swarm size | 0–3 gaps, single domain (2–3 agents, no PM) | 4–10 gaps, two or three domains (4–6 agents with PM) | 11+ gaps or cross-cutting domains (6–8 agents with PM) | +| [`/gap-analysis`](../han-research/docs/skills/gap-analysis.md) | Default-on swarm size | 0–3 gaps, single domain (2–3 agents, no PM) | 4–10 gaps, two or three domains (4–6 agents with PM) | 11+ gaps or cross-cutting domains (6–8 agents with PM) | | [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | Lightweight vs team mode + team size + round cap | 2–3 files, single system (lightweight, 1 round) | 3–5 files, one cross-cutting concern (team, 3–4, 2 rounds) | More than 5 files, multiple systems (team, 4–5, 3 rounds) | | [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Review-team size cap | Single subsystem (team cap 2) | Two to three subsystems (team cap 3–4) | Cross-service or security-sensitive (team cap 4–5) | | [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Implementation-team size + round cap | Single subsystem (team cap 3, 1 round) | Two to three subsystems (team cap 4–5, 2 rounds) | Cross-service or security-sensitive (team cap 6–8, 3 rounds) | -| [`/research`](../han-research/docs/skills/research.md) | Research-analyst angle count + reach | One domain, few or no options, narrow reach (2–3 agents) | Two to three domains or several options, codebase-plus-web reach (3–5 agents) | Many options across multiple domains, or full-breadth request (5–8 agents) | +| [`/research`](../han-research/docs/skills/research.md) | Research-analyst angle count + reach | One domain, few or no options, narrow reach (2–3 agents) | Two to three domains or several options, codebase-plus-web reach (3–5 agents) | Many options across multiple domains, or full-breadth request (5–8 agents) | Read each skill's **Sizing** section for the full per-skill rules. diff --git a/docs/yagni.md b/docs/yagni.md index f75fdaaf..50b89c28 100644 --- a/docs/yagni.md +++ b/docs/yagni.md @@ -104,26 +104,26 @@ Anti-patterns from this list force a YAGNI finding regardless of severity rules. YAGNI applies in two postures: **producing** (when a skill drafts an artifact) and **reviewing** (when a skill or agent audits one). -| Surface | What YAGNI gates | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Every behavior, edge case, alternate flow, and coordination in the spec. Speculative behaviors land in a `## Deferred (YAGNI)` section. | -| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Every plan step, abstraction, infrastructure addition, observability hook, and rollout step. A YAGNI sweep runs before the plan is committed. | -| [`/plan-a-phased-build`](../han-planning/docs/skills/plan-a-phased-build.md) | Every phase. Phases whose only justification is "completeness of the roadmap" get deferred or merged into a smaller adjacent phase. | -| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | A YAGNI review pillar runs alongside correctness, completeness, and risk. Every uncited item raises a `Category: YAGNI candidate` finding. | -| [`/code-review`](../han-coding/docs/skills/code-review.md) | YAGNI is **advisory-only** and runs as a two-pass procedure (Pass 1 evidence test against Gate 1; Pass 2 named anti-pattern match). Each finding records the failing evidence type, the matched anti-pattern, and the simpler form considered. Findings surface speculative additions but do not block a clean review on their own; the reviewer's posture is "make the cost of inclusion visible," not "reject the change." Skipped in Mode B (uncommitted changes) and Mode C (no git) unless explicitly requested via the focus-areas argument, since no diff exists to distinguish introduced code from pre-existing code. | -| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified only when the project does the thing the standard governs _today_ and the standard solves a real, concrete problem the team is currently hitting. | -| [`/automated-test-planning`](../han-coding/docs/skills/automated-test-planning.md) | A YAGNI sweep removes speculative tests: for code paths that don't exist, hypothetical adversaries, or branches the change doesn't touch. | +| Surface | What YAGNI gates | +| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`/plan-a-feature`](../han-planning/docs/skills/plan-a-feature.md) | Every behavior, edge case, alternate flow, and coordination in the spec. Speculative behaviors land in a `## Deferred (YAGNI)` section. | +| [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) | Every plan step, abstraction, infrastructure addition, observability hook, and rollout step. A YAGNI sweep runs before the plan is committed. | +| [`/plan-a-phased-build`](../han-planning/docs/skills/plan-a-phased-build.md) | Every phase. Phases whose only justification is "completeness of the roadmap" get deferred or merged into a smaller adjacent phase. | +| [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md) | A YAGNI review pillar runs alongside correctness, completeness, and risk. Every uncited item raises a `Category: YAGNI candidate` finding. | +| [`/code-review`](../han-coding/docs/skills/code-review.md) | YAGNI is **advisory-only** and runs as a two-pass procedure (Pass 1 evidence test against Gate 1; Pass 2 named anti-pattern match). Each finding records the failing evidence type, the matched anti-pattern, and the simpler form considered. Findings surface speculative additions but do not block a clean review on their own; the reviewer's posture is "make the cost of inclusion visible," not "reject the change." Skipped in Mode B (uncommitted changes) and Mode C (no git) unless explicitly requested via the focus-areas argument, since no diff exists to distinguish introduced code from pre-existing code. | +| [`/coding-standard`](../han-coding/docs/skills/coding-standard.md) | A standard is justified only when the project does the thing the standard governs _today_ and the standard solves a real, concrete problem the team is currently hitting. | +| [`/automated-test-planning`](../han-coding/docs/skills/automated-test-planning.md) | A YAGNI sweep removes speculative tests: for code paths that don't exist, hypothetical adversaries, or branches the change doesn't touch. | | [`/architectural-decision-record`](../han-documentation/docs/skills/architectural-decision-record.md) | An ADR requires a **forcing function** today: a real decision being made now, with consequences. ADRs about decisions that don't have a forcing function are YAGNI. | -| [`/tdd`](../han-coding/docs/skills/tdd.md) | Enforcing in the refactor step and the test list. A scenario joins the test list only with evidence; speculative scenarios are deferred with a reopen trigger. Refactor removes duplication but defers speculative abstraction (the Rule of Three). Correctness-and-placement standards still apply in green. | -| [`project-manager`](../han-core/docs/agents/project-manager.md) | The YAGNI Evidence Gate protocol. Every committed proposal in a facilitated discussion must cite evidence; uncited proposals are challenged or deferred. | -| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | The YAGNI Evidence Sweep protocol. Flags hidden assumptions and uncited additions during stress-testing. | -| [`software-architect`](../han-core/docs/agents/software-architect.md) | Architectural recommendations cite the change-history or coupling evidence that justifies the recommendation. Speculative abstractions are deferred. | -| [`system-architect`](../han-core/docs/agents/system-architect.md) | Cross-service topology changes cite the seam-crossing evidence (data ownership conflict, failure-domain leak, integration shape) that justifies them. | -| [`test-engineer`](../han-core/docs/agents/test-engineer.md) | The Speculative Test rule. Tests for code paths that don't exist, hypothetical adversaries, or unreachable branches are flagged. | -| [`edge-case-explorer`](../han-core/docs/agents/edge-case-explorer.md) | The Speculative Edge Case rule. Edge cases for code paths that don't exist or for inputs that internal callers fully control are flagged. | -| [`data-engineer`](../han-core/docs/agents/data-engineer.md) | The Speculative Data Machinery rule. Indexes for queries that don't run, audit columns nobody reads, denormalization for read patterns that don't exist. | -| [`devops-engineer`](../han-core/docs/agents/devops-engineer.md) | The Premature Operational Machinery rule. Runbooks for alerts that have never fired, SLOs for traffic that doesn't yet exist, multi-region infrastructure for unproven single-region workloads. | -| [`on-call-engineer`](../han-core/docs/agents/on-call-engineer.md) | The Premature Operability Machinery rule, applied at the application source line. Circuit breakers, bulkheads, idempotency tables, kill switches, dead-letter queues, and custom error types are deferred when no evidence shows the system needs them now (named upstream finding, existing code path that breaks, three current uses, measured incident, applicable regulation). | +| [`/tdd`](../han-coding/docs/skills/tdd.md) | Enforcing in the refactor step and the test list. A scenario joins the test list only with evidence; speculative scenarios are deferred with a reopen trigger. Refactor removes duplication but defers speculative abstraction (the Rule of Three). Correctness-and-placement standards still apply in green. | +| [`project-manager`](../han-core/docs/agents/project-manager.md) | The YAGNI Evidence Gate protocol. Every committed proposal in a facilitated discussion must cite evidence; uncited proposals are challenged or deferred. | +| [`junior-developer`](../han-core/docs/agents/junior-developer.md) | The YAGNI Evidence Sweep protocol. Flags hidden assumptions and uncited additions during stress-testing. | +| [`software-architect`](../han-core/docs/agents/software-architect.md) | Architectural recommendations cite the change-history or coupling evidence that justifies the recommendation. Speculative abstractions are deferred. | +| [`system-architect`](../han-core/docs/agents/system-architect.md) | Cross-service topology changes cite the seam-crossing evidence (data ownership conflict, failure-domain leak, integration shape) that justifies them. | +| [`test-engineer`](../han-core/docs/agents/test-engineer.md) | The Speculative Test rule. Tests for code paths that don't exist, hypothetical adversaries, or unreachable branches are flagged. | +| [`edge-case-explorer`](../han-core/docs/agents/edge-case-explorer.md) | The Speculative Edge Case rule. Edge cases for code paths that don't exist or for inputs that internal callers fully control are flagged. | +| [`data-engineer`](../han-core/docs/agents/data-engineer.md) | The Speculative Data Machinery rule. Indexes for queries that don't run, audit columns nobody reads, denormalization for read patterns that don't exist. | +| [`devops-engineer`](../han-core/docs/agents/devops-engineer.md) | The Premature Operational Machinery rule. Runbooks for alerts that have never fired, SLOs for traffic that doesn't yet exist, multi-region infrastructure for unproven single-region workloads. | +| [`on-call-engineer`](../han-core/docs/agents/on-call-engineer.md) | The Premature Operability Machinery rule, applied at the application source line. Circuit breakers, bulkheads, idempotency tables, kill switches, dead-letter queues, and custom error types are deferred when no evidence shows the system needs them now (named upstream finding, existing code path that breaks, three current uses, measured incident, applicable regulation). | ## The Deferred (YAGNI) section format diff --git a/han-atlassian/docs/skills/code-overview-to-confluence.md b/han-atlassian/docs/skills/code-overview-to-confluence.md index ee04ba73..f32e0775 100644 --- a/han-atlassian/docs/skills/code-overview-to-confluence.md +++ b/han-atlassian/docs/skills/code-overview-to-confluence.md @@ -41,7 +41,7 @@ helps you decide _when_ and _how_ to use the skill. For what the skill does inte `/code-overview` for a local-only run. It never silently falls back to local. - **The overview lands in a scratch file first.** `/code-overview` always writes its overview to a scratch file outside your repo (for example `${TMPDIR:-/tmp}/code-overview-.md`), so it never gets committed unless you move it there -yourself. + yourself. - **You review before publishing.** The skill shows you the scratch-file path so you can open and read the overview, then asks how to publish. Nothing is posted until you choose. - **You must provide the location.** The skill does not search Confluence for the right page. A real Confluence instance diff --git a/han-coding/skills/code-overview/references/overview-template.md b/han-coding/skills/code-overview/references/overview-template.md index 1e2efd5b..f3ae032f 100644 --- a/han-coding/skills/code-overview/references/overview-template.md +++ b/han-coding/skills/code-overview/references/overview-template.md @@ -87,7 +87,6 @@ _Scope: {what this chart represents — e.g. the request path from entry to resp flowchart TD {the main process flow} ``` -```` {One or two sentences walking the reader through the chart at a high level — read as how the code delivers on the why above.} @@ -110,7 +109,7 @@ line each on what each is for.} ## PR mode — explaining a set of changes -```markdown +````markdown # Change Overview: {short name of the pull request or branch} {Intro paragraph: one or two sentences naming what is being examined — which @@ -163,7 +162,7 @@ system; what it omits, if partial}._ ```mermaid flowchart TD {how the change moves through or affects the system} -```` +``` {One or two sentences on how to read the chart.} @@ -176,6 +175,4 @@ quality or risk judgment; that is code-review's job, not this skill's. --> {The concrete entry points — the specific files or components — where the change is densest or most interconnected, with one line each on why a reviewer should slow down there.} -``` - -``` +```` diff --git a/han-documentation/skills/project-documentation/SKILL.md b/han-documentation/skills/project-documentation/SKILL.md index b341e04b..c8efc792 100644 --- a/han-documentation/skills/project-documentation/SKILL.md +++ b/han-documentation/skills/project-documentation/SKILL.md @@ -90,18 +90,22 @@ Lead with behavior. These rules make the doc an overview first and a reference s component listings under the `## Technical Reference` region, below the behavioral spine. Treat them as lookup material, not the document's main body. -Apply to every section: 5. **Absolute file paths** from repo root (e.g., `src/services/auth.ts`, not `./auth.ts`). 6. -**Prefer pointers over long code.** In Technical Reference, point to the file and function and include a short -illustrative snippet only where the source is non-obvious. Do not reproduce long (10-30 line) source blocks; link to the -source instead. 7. **Code fence language identifiers** must match the project's actual languages (from Step 1). 8. -**Document constants and magic numbers** with their actual values in the Constants table. 9. **Skip CONDITIONAL -sections** from the template that don't apply. Don't include empty sections. 10. **One plain-language description** in -the title area summarizing what the feature does. 11. **Separate backend and frontend content.** Use `### Backend` / -`### Frontend` sub-headings for cross-cutting features; skip sub-headings for single-layer features. 12. **Diagrams are -Mermaid, not ASCII.** Render the Architecture diagram, any Primary Flow diagram, and the Component Hierarchy as Mermaid -in a ` ```mermaid ` fence — `flowchart` for structure and trees, `sequenceDiagram` for actor-to-system exchanges. Label -nodes with parts a reader recognizes and label edges with what passes between them. Keep each diagram to the parts that -matter; a reader should grasp the shape at a glance. +Apply to every section: + +5. **Absolute file paths** from repo root (e.g., `src/services/auth.ts`, not `./auth.ts`). +6. **Prefer pointers over long code.** In Technical Reference, point to the file and function and include a short + illustrative snippet only where the source is non-obvious. Do not reproduce long (10-30 line) source blocks; link to + the source instead. +7. **Code fence language identifiers** must match the project's actual languages (from Step 1). +8. **Document constants and magic numbers** with their actual values in the Constants table. +9. **Skip CONDITIONAL sections** from the template that don't apply. Don't include empty sections. +10. **One plain-language description** in the title area summarizing what the feature does. +11. **Separate backend and frontend content.** Use `### Backend` / `### Frontend` sub-headings for cross-cutting + features; skip sub-headings for single-layer features. +12. **Diagrams are Mermaid, not ASCII.** Render the Architecture diagram, any Primary Flow diagram, and the Component + Hierarchy as Mermaid in a ` ```mermaid ` fence — `flowchart` for structure and trees, `sequenceDiagram` for + actor-to-system exchanges. Label nodes with parts a reader recognizes and label edges with what passes between them. + Keep each diagram to the parts that matter; a reader should grasp the shape at a glance. **Updating existing documents:** Read the entire existing document first and note all content sources (existing doc, content migrated from CLAUDE.md or other files, any other inputs). Preserve the existing structure; don't reorganize diff --git a/han-planning/skills/plan-a-feature/SKILL.md b/han-planning/skills/plan-a-feature/SKILL.md index ff22d8c7..29a457c3 100644 --- a/han-planning/skills/plan-a-feature/SKILL.md +++ b/han-planning/skills/plan-a-feature/SKILL.md @@ -437,20 +437,21 @@ After all review agents return, compile their findings. **Do not dump raw findin sentence behaviorally and either extracting the mechanic to a `T#` note (if load-bearing) or removing it entirely (if pure implementation or discoverable from code). Do not escalate these to the user unless the rewrite would change the feature's meaning. - -5a. **`YAGNI candidate` findings** — apply the YAGNI rule per -[../../references/yagni-rule.md](../../references/yagni-rule.md). For each finding, three resolution paths exist: (a) -cite the missing evidence (per the rule's evidence test) and keep the spec item — record the citation in the relevant -`D#`'s `Evidence:` field and close the finding; (b) replace with the strictly simpler version that satisfies the same -evidence — update the spec sentence and the related `D#`, list the larger version under that `D#`'s -`Rejected alternatives:` with the reason "simpler version satisfies the same evidence"; (c) demote to the spec's -`## Deferred (YAGNI)` section with the reopening trigger named, removing the inline behavior from the affected sections. -Surface YAGNI deferrals to the user in Step 7's escalation pass so the user can override consciously, but do not require -user input when evidence resolves the finding directly. 6. **Escalate only what genuinely needs the user.** For findings -that remain open, draft a recommended answer with rationale and alternatives, the same way Step 4 surfaces questions. -Present them to the user together, organized by the decision they affect — not by which agent raised them. 7. **Capture -the user's answers** in the relevant `D#` entry in `artifacts/decision-log.md`, finish populating the `F#` entry -(`Resolved by: user input`), update any dependent decisions or tech-notes, and keep all files' cross-refs in sync. +6. **`YAGNI candidate` findings** — apply the YAGNI rule per + [../../references/yagni-rule.md](../../references/yagni-rule.md). For each finding, three resolution paths exist: (a) + cite the missing evidence (per the rule's evidence test) and keep the spec item — record the citation in the relevant + `D#`'s `Evidence:` field and close the finding; (b) replace with the strictly simpler version that satisfies the same + evidence — update the spec sentence and the related `D#`, list the larger version under that `D#`'s + `Rejected alternatives:` with the reason "simpler version satisfies the same evidence"; (c) demote to the spec's + `## Deferred (YAGNI)` section with the reopening trigger named, removing the inline behavior from the affected + sections. Surface YAGNI deferrals to the user in Step 7's escalation pass so the user can override consciously, but do + not require user input when evidence resolves the finding directly. +7. **Escalate only what genuinely needs the user.** For findings that remain open, draft a recommended answer with + rationale and alternatives, the same way Step 4 surfaces questions. Present them to the user together, organized by + the decision they affect — not by which agent raised them. +8. **Capture the user's answers** in the relevant `D#` entry in `artifacts/decision-log.md`, finish populating the `F#` + entry (`Resolved by: user input`), update any dependent decisions or tech-notes, and keep all files' cross-refs in + sync. ## Step 8: Project Manager Synthesis diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md index 55f3df3c..2214c61c 100644 --- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md +++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md @@ -122,18 +122,18 @@ disambiguation leaves a gap that Claude can fall through. **Commonly confused skill pairs and their boundary statements:** -| Skill A | Skill B | How to disambiguate | -| ----------------------- | ------------------------------- | ----------------------------------------------- | -| `code-review` | `post-code-review-to-pr` | Local analysis vs. GitHub integration | -| `update-pr-description` | `post-code-review-to-pr` | PR body/summary vs. review comments | -| `project-documentation` | `architectural-decision-record` | Feature/system docs vs. architectural decisions | -| `project-documentation` | `coding-standard` | Feature/system docs vs. coding standards | -| `coding-standard` | `architectural-decision-record` | Enforceable rules vs. decision records | -| `project-discovery` | `project-documentation` | Tech stack scanning vs. feature/system docs | -| `automated-test-planning` | `code-review` | Test coverage plans vs. code quality review | -| `automated-test-planning` | `manual-test-planning` | Coverage-gap analysis vs. hand-run test steps | -| `automated-test-planning` | `iterative-plan-review` | Test plans vs. refining work plans | -| `brand-messaging` | `writing-style` | Positioning/ICP/campaigns vs. prose style/voice | +| Skill A | Skill B | How to disambiguate | +| ------------------------- | ------------------------------- | ----------------------------------------------- | +| `code-review` | `post-code-review-to-pr` | Local analysis vs. GitHub integration | +| `update-pr-description` | `post-code-review-to-pr` | PR body/summary vs. review comments | +| `project-documentation` | `architectural-decision-record` | Feature/system docs vs. architectural decisions | +| `project-documentation` | `coding-standard` | Feature/system docs vs. coding standards | +| `coding-standard` | `architectural-decision-record` | Enforceable rules vs. decision records | +| `project-discovery` | `project-documentation` | Tech stack scanning vs. feature/system docs | +| `automated-test-planning` | `code-review` | Test coverage plans vs. code quality review | +| `automated-test-planning` | `manual-test-planning` | Coverage-gap analysis vs. hand-run test steps | +| `automated-test-planning` | `iterative-plan-review` | Test plans vs. refining work plans | +| `brand-messaging` | `writing-style` | Positioning/ICP/campaigns vs. prose style/voice | **Before (no boundary, `project-documentation`):** diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md index 4bcc9e96..3da77349 100644 --- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md +++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md @@ -311,7 +311,6 @@ async function fetchUser(id: string) { } } ``` -```` ### Input validation at boundaries @@ -335,15 +334,17 @@ Functions with network calls or file writes must name the side effect. ``` ```` + Each convention is independently parseable: heading, rule, example. ### Rule: Resolve variation at the point of use When a step drives several similar items that each take a slightly different set of inputs — dispatching sub-agents with different reference files, applying rules each scoped to different files — do not express the variation as a matrix the model must join against a separate list. Reading a table, extracting each item's cells, and binding them to a separate enumeration makes the model do an in-head join. That such a join trips the model is a reasoned bet — by analogy to documented weaknesses in large-table lookup and multi-hop binding, though no study tests it at this small a scale — so prefer to remove the join rather than rely on the model to get it right. Give each item its resolved, self-contained set instead. -Keep the *source* normalized — author the shared parts once — but denormalize into the point of use, resolving the variation with a deterministic step (a script, or the driver that assembles each dispatch) where one exists. This does not contradict [Progressive Disclosure](./progressive-disclosure.md): a reference resolved by a Read co-locates its content at the point of use, so it is not an in-head join. See [Context Hygiene](./context-hygiene.md) for the loadable-pointer vs. in-head-reference distinction. +Keep the _source_ normalized — author the shared parts once — but denormalize into the point of use, resolving the variation with a deterministic step (a script, or the driver that assembles each dispatch) where one exists. This does not contradict [Progressive Disclosure](./progressive-disclosure.md): a reference resolved by a Read co-locates its content at the point of use, so it is not an in-head join. See [Context Hygiene](./context-hygiene.md) for the loadable-pointer vs. in-head-reference distinction. **Before (variation as a matrix the model must join):** + ```markdown ## Step 4: Dispatch Reviewers @@ -359,7 +360,7 @@ Prompts: 1. Review for injection and authz. 2. Review schema normalization and indexes. 3. Review endpoint contracts. -```` +``` The model must read the matrix, extract each reviewer's "yes" columns, and bind them to the right numbered prompt before it can dispatch anything. diff --git a/han-research/skills/research/SKILL.md b/han-research/skills/research/SKILL.md index 7c76b6f6..bd5b048b 100644 --- a/han-research/skills/research/SKILL.md +++ b/han-research/skills/research/SKILL.md @@ -154,10 +154,10 @@ options). A conversational override ("research this broadly") is equivalent to ` **Signal-selected angle — added when present and the band allows:** -| Angle | Add when | Min band | -| --------------------------------------------------------- | ----------------------------------------------------------- | -------- | -| `han-core:codebase-explorer` (codebase-grounded evidence) | A repository exists and the question has a codebase bearing | Small | -| Additional parallel `han-research:research-analyst` angles | The question spans multiple domains or many options | Medium | +| Angle | Add when | Min band | +| ---------------------------------------------------------- | ----------------------------------------------------------- | -------- | +| `han-core:codebase-explorer` (codebase-grounded evidence) | A repository exists and the question has a codebase bearing | Small | +| Additional parallel `han-research:research-analyst` angles | The question spans multiple domains or many options | Medium | Roster caps by band: **small** runs one `han-research:research-analyst` plus `han-core:codebase-explorer` if a repo bears on the question, then `han-core:adversarial-validator` (2–3 agents); **medium** runs two to three parallel