@groupby/ai-dev 0.5.15 → 0.5.17

package/teams/firstspirit-caas/resources/mcp-setup.md

@@ -0,0 +1,57 @@
+# FirstSpirit CaaS — jira-tools MCP setup
+
+Most FirstSpirit CaaS skills (`get-jira-ticket`, `create-jira-ticket`, `review`,
+`handle-red-cve-plan`, `write-releasenotes`, and others) call tools served by a
+local **`jira-tools`** MCP server. The server code ships in this team's `mcp/`
+folder and installs to `docs/ai/mcp/jira-tools.py`.
+
+> This team was ported from a Claude Code plugin
+> (`crownpeak-claudecode-marketplace/plugins/planetexpress`). The plugin
+> registered the MCP server automatically via `.mcp.json` and collected tokens
+> via `plugin.json` `userConfig`. The `ai-dev` CLI only copies files — it does
+> **not** register MCP servers or prompt for tokens. Register the server
+> yourself using the config below before using the Jira/Bamboo/Bitbucket skills.
+
+## Requirements
+
+- `python3` on PATH.
+- Access tokens for Jira, Bitbucket (Server/Data Center), and Bamboo.
+
+### Tokens
+
+| Env var | How to create |
+| --- | --- |
+| `JIRA_TOKEN` | `<Jira>/secure/ViewProfile.jspa` → Personal Access Tokens (Bearer auth). |
+| `BITBUCKET_TOKEN` | `<Bitbucket>/plugins/servlet/access-tokens/manage`. Needs at least Repository read + Pull request write. |
+| `BAMBOO_TOKEN` | `<Bamboo>/users/createPersonalAccessToken.action` (Bearer auth). Used to read CI build/job/log details and download artifacts. |
+
+Keep tokens out of source control. Supply them via your MCP client's secret
+handling or the shell environment.
+
+## Register the server
+
+Point the command at wherever the server was installed
+(`docs/ai/mcp/jira-tools.py` by default). Adjust base URLs for your instances.
+
+```json
+{
+  "mcpServers": {
+    "jira-tools": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["docs/ai/mcp/jira-tools.py"],
+      "env": {
+        "JIRA_BASE_URL": "https://jira.crownpeak.com",
+        "JIRA_TOKEN": "<your jira token>",
+        "BITBUCKET_BASE_URL": "https://git.e-spirit.de",
+        "BITBUCKET_TOKEN": "<your bitbucket token>",
+        "BAMBOO_BASE_URL": "https://ci.e-spirit.de",
+        "BAMBOO_TOKEN": "<your bamboo token>"
+      }
+    }
+  }
+}
+```
+
+Once registered, the server exposes the `jira-tools` toolset the skills expect
+(Jira issues/comments/transitions, Bitbucket PRs, Bamboo builds/artifacts).

package/teams/firstspirit-caas/skills/chronicle/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: chronicle
+description: Use when the user asks to keep, start, update, or read a running high-level summary of the work done this session — phrases like "chronicle this session", "update the chronicle", "keep a chronicle", "session chronicle", "where are we on this", "what have we done so far". Triggers on requests for a living, high-level record of session work written to ./.claude/plans/.
+---
+
+# Chronicle
+
+## Overview
+
+Maintains a **living, high-level chronicle** of the work done in a session, stored as
+markdown in `./.claude/plans/`. The chronicle reflects the **net current state** of the
+work — not a chronological log, and not steps that were later undone. No code-line detail.
+
+**Core principle:** The chronicle is a *living summary edited to match the present*, not an
+append-only log. When work is superseded or reverted, the entry is rewritten or removed —
+never struck through, never preserved as history.
+
+**Describe the work, not the workflow.** Record what the system/code now does, what was
+decided, and what is still missing — as if describing the state of the product to someone who
+does not care how it got there. Never record process/meta: "ticket specified", "plan written",
+"task N complete", "reviewed / review passed", commit counts or ranges, plan/PR/branch
+bookkeeping. Those are how the work happened, not what the work is.
+
+## When to Use
+
+- User asks to chronicle / start / update / refresh a session summary.
+- User asks "where are we" / "what have we done so far" and wants it persisted.
+- After the skill has been invoked once in a session: re-update the chronicle following any
+  *later* prompt that significantly changes state (see Hybrid upkeep).
+
+**Not for:** JIRA ticket comments (use `summarise-for-jira-comment`), session
+retrospectives (use `retrospect`), or mechanical step-by-step plans (write those directly to
+`./.claude/plans/`).
+
+## Chronicle file
+
+Path: `./.claude/plans/<TICKET>-chronicle.md`
+
+- `<TICKET>` = JIRA key matched in the current branch (`git rev-parse --abbrev-ref HEAD`)
+  via `[A-Z][A-Z0-9]+-[0-9]+`.
+  - `issue/HP-1234` → `HP-1234-chronicle.md`
+  - `feature/HP-1234-foo-bar` → `HP-1234-chronicle.md`
+- No JIRA key → sanitized branch name (slashes → dashes): `feature-spike-chronicle.md`.
+
+## Workflow on invoke
+
+1. **Resolve path** — read the branch, derive `<TICKET>` or branch fallback.
+2. **Gather state** — from two sources only:
+   - the conversation already in context (asked / decided / done);
+   - git: `git status`, recent commits on the branch, `git diff --stat`.
+
+   Do not parse the transcript `.jsonl`. Do not run a script.
+3. **Build or reconcile:**
+   - File absent → write a fresh best-effort summary.
+   - File present → **reconcile to current state**: rewrite changed entries, delete entries
+     for undone/superseded work, add newly-significant work. Edit toward the present — never
+     append blindly.
+4. **Write** the file and report its path.
+
+## File structure
+
+```markdown
+# Chronicle: <TICKET or branch>
+
+_Last updated: <YYYY-MM-DD>_
+
+## Goal
+<one or two lines: what this work is trying to achieve>
+
+## Current state
+<what the system/code now does — capabilities and behavior, not tasks completed>
+
+## Key decisions
+<notable choices and why — high level>
+
+## Open / in-progress
+<what the system cannot yet do — missing capabilities, not unmerged/unreviewed work>
+```
+
+Omit any section that is empty.
+
+## Hybrid upkeep
+
+Once invoked in a session, re-update the chronicle after any *subsequent* prompt that
+**significantly changes state**:
+
+- **Significant** — a feature/fix completed, a design decision made, scope changed, a new
+  area of work started.
+- **Skip** — typos, formatting, read-only exploration, dead-ends tried and removed.
+
+This upkeep is best-effort. The authoritative refresh is always a fresh invocation, which
+re-reconciles against git + context.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Logging process/meta: "ticket specified", "plan written", "task N done", "review passed", "16 commits on branch" | Describe the work, not the workflow. State what the system now does / decided / missing. |
+| Naming plan/PR/branch artifacts or commit ranges | Drop them — the chronicle describes the product, not the bookkeeping. |
+| "Open" listing unmerged / no-PR-raised status | Open = missing capabilities, not integration bookkeeping. |
+| Appending every change as a dated log entry | Reconcile to current state; rewrite/remove superseded entries. |
+| Including `file:line`, code blocks, command lists | High level only — net outcomes, not mechanics. |
+| Keeping entries for work that was reverted | Delete them. The chronicle shows the present, not history. |
+| Parsing the session `.jsonl` transcript | Use in-context conversation + git only. |
+| Writing to the wrong file each session | Path is derived from the branch ticket — same ticket, same file. |

package/teams/firstspirit-caas/skills/create-jira-ticket/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: create-jira-ticket
+description: Use when the user asks to create, file, open, or raise a JIRA ticket — phrases like "create a HP ticket for X", "file a ticket", "open a JIRA for Y", "ticket this up", "make a Story for Z". Triggers on requests to create a new ticket via the JIRA MCP tool.
+---
+
+# Create JIRA Ticket
+
+## Overview
+
+Drafts a high-level ticket (what + why), presents the full fields for explicit approval, and creates the ticket via `mcp__plugin_planetexpress_jira-tools__create_jira_ticket`. When the conversation makes an explicit relationship to another ticket clear, it also proposes issue links — shown together with the description, and created after the ticket via `mcp__plugin_planetexpress_jira-tools__link_jira_issues`, using only relationship types fetched from `get_jira_link_types`.
+
+**Core principle:** A ticket says what needs to happen and why. Strong defaults exclude file paths, code blocks, counts, acceptance criteria, and step-by-step plans. Implementation belongs in the PR; mechanical task lists belong in `./.claude/plans/`; the ticket is the *why* and the *what*, nothing more.
+
+## When to use
+
+- User asks to create / file / open / raise a JIRA ticket, story, task, bug, or sub-task
+- User says "ticket this up", "make a JIRA for X", "create a HP- for Y", or similar
+
+## When NOT to use
+
+- User wants a written *plan* in the workspace — that is a `./.claude/plans/*.md` file, not a JIRA ticket
+- User wants to comment on an existing ticket — use `mcp__plugin_planetexpress_jira-tools__add_jira_comment` directly
+- User wants to summarise completed work for a ticket — use `summarise-for-jira-comment`
+- User wants to update an existing ticket's description — use `specify`
+
+## Workflow
+
+1. **Identify the project key**
+   - Default: parse the leading `[A-Z]+` of the ticket key in the current branch name (e.g., `feature/HP-1615-...` → `HP`)
+   - Override: an explicit project key in the user's message
+   - Unclear or multiple plausible projects: ask before drafting
+
+2. **Identify summary, issue type, and any fields the user named**
+   - **Summary:** one short imperative line. Match the project's prevailing style if visible from recent ticket fetches. No trailing punctuation.
+   - **Issue type:** by default choose between `Story` and `Escaped Bug` — pick whichever fits the ask (new work → Story; defect that slipped past release → Escaped Bug). Only use other types (Task, Bug, Sub-task, etc.) when the user explicitly names them. If Story vs Escaped Bug is genuinely ambiguous, ask.
+   - **Parent** (required for Sub-task), **priority**, **labels**, **assignee**: only set when the user named them. Do not invent labels or guess priority.
+
+3. **Gather just enough context for the description**
+   - Read the conversation. If the user pointed at code, branches, plans, or other tickets, pull that context.
+   - Stop as soon as you can write *why* and *what*. Do not enumerate files, count imports, or read the whole codebase to "be thorough".
+
+4. **Identify issue-link candidates (explicit relationships only)**
+   - Scan only what is already in context — the conversation, the branch ticket, already-fetched tickets / dev-info, referenced plans. **Never search JIRA** to find tickets to link.
+   - Propose a link only when the relationship is *explicitly clear* from that context (e.g. the user said "this follows on from HP-100", a plan notes it is blocked by HP-200, the branch continues prior work). A bare ticket mention or mere topical overlap is **not** a link.
+   - Direction is from the new ticket's perspective: `from_issue = (new ticket)`, `to_issue = <context ticket>`, `relationship = <phrase as stated>`.
+   - **Fetch-then-restrict:** if (and only if) you have at least one candidate, call `mcp__plugin_planetexpress_jira-tools__get_jira_link_types` **before presenting**, and keep a candidate only if its relationship matches a known type's `outward` or `inward` phrase. If a clearly-stated relationship has no matching type, do **not** invent one — tell the user and show the available phrases so they can choose. With no candidates, skip the fetch entirely.
+
+5. **Draft** in the default voice and shape (see next section).
+
+6. **Present in chat** — show all ticket fields verbatim, exactly as they will be sent, followed by the proposed links:
+
+   ```
+   Project:     HP
+   Issue type:  Story
+   Summary:     <one-line title>
+   Priority:    <only if set>
+   Labels:      <only if set>
+   Assignee:    <only if set>
+   Parent:      <only if Sub-task>
+
+   Description:
+   <body, exactly as it will appear in JIRA, in JIRA wiki markup>
+
+   Links:
+   - (new ticket) <relationship> <TICKET-KEY>
+   - (new ticket) <relationship> <TICKET-KEY>
+   ```
+
+   The new ticket has no key yet, so its side reads `(new ticket)`. When there are no qualifying links, show `Links: (none — tell me if you want to add one)`. Then end with:
+   > Reply 'create' to file the ticket (and its links), or give edits.
+
+7. **Wait for explicit approval (strict gate + edits)**
+   - Affirmative-and-explicit ("create", "yes, create", "file it", "go ahead and create", "ship it") → create the ticket and its links
+   - Edits ("shorter", "drop that bullet", "drop the HP-100 link", "make it relates to", "change type to Bug") → revise, re-present **all fields and links** verbatim, wait again
+   - Anything else (silence, questions, "looks good", mixed feedback) → do **not** create; treat as edits or a question
+   - The strict gate covers links too: never create a link the user did not explicitly approve in the presented block.
+
+8. **Create**
+   - Call `mcp__plugin_planetexpress_jira-tools__create_jira_ticket` with the approved fields; capture the new ticket key.
+   - For each approved link, call `mcp__plugin_planetexpress_jira-tools__link_jira_issues` with `from_issue = <new key>`, `to_issue = <target>`, `relationship = <phrase>`.
+   - Report the ticket key/URL **and** each link's outcome. A link can still fail server-side (e.g. missing target); report that failure verbatim, do **not** claim it succeeded, and offer to retry. The ticket is never rolled back.
+
+## Voice & format
+
+**Default shape (use this unless something forces otherwise):**
+
+- 1–3 sentences of context / *why*
+- 1–2 sentences of *what* needs to happen
+- *Optionally:* a short bulleted list of **non-obvious gotchas** — file or class names are allowed here, but only when the gotcha is specifically about that piece of code
+
+That is the whole template. No `Scope` / `Out of scope` / `Acceptance criteria` / `Risks` / `Reference` headers. No estimates. No counts.
+
+**Voice:** neutral, factual, present/imperative tense. Describes the work, not the author. Not first person.
+
+**Markup:** JIRA wiki markup. Use `*bold*`, `_italics_`, `-` for bullets, `{{monospace}}` for the rare inline identifier. Do not paste fenced code blocks unless code is genuinely the point of the ticket.
+
+**Strong defaults — exclude unless they are the actual point of the ticket:**
+
+- Code blocks or inline code
+- File counts, import counts, line counts ("102 files import…", "66 production + 36 test")
+- Exhaustive lists of affected files / classes / methods / packages
+- Mechanical sub-tasks ("rename `X.java` → `Y.java`", "drop annotation `Z`", "promote `compileOnly` to `implementation`")
+- Acceptance criteria, "out of scope" sections, risk lists, build-command checks
+- Time / effort estimates
+- Links to plan files in `./.claude/plans/` (those are not deliverables and are not committed)
+
+**Exception clause:** include any of the above when the work *is* about that specific thing — a ticket whose whole point is "rip out `FooService`" can name it; a ticket about "fix the off-by-one in `BarController#paginate`" can point at it.
+
+**Length:** if the description scrolls in the chat, it is wrong. Most descriptions land in under 12 lines.
+
+### Example pair
+
+Hypothetical work: *finish the Jackson 3 migration after Spring Boot 4 lands*.
+
+**❌ Bad (a plan, not a ticket — taken from a real prior session):**
+
+> Drop the `spring-boot-jackson2` shim and migrate the codebase from Jackson 2 (`com.fasterxml.jackson.*`) to Jackson 3 (`tools.jackson.*`). Estimated 2–3 days for one engineer.
+>
+> *Scope (mechanical, ~80%):*
+> - 102 Java files import `com.fasterxml.jackson.*` (66 production + 36 test). Pure prefix rename.
+> - Top-affected: `databind.ObjectMapper` (66 files), `annotation.JsonProperty` (12), `core.JsonProcessingException` (9)…
+>
+> *Real semantic work:*
+> - 20 files instantiate `new ObjectMapper()` — Jackson 3 mappers are immutable; migrate to `JsonMapper.builder()...build()`.
+> - 18 test files using `Jackson2Tester` — swap to whatever Boot 4 ships natively.
+> - 1 `Jackson2ObjectMapperBuilderCustomizer` in `datagenerator/.../DatageneratorSpringConfiguration.java` → `JsonMapperBuilderCustomizer`.
+> - …
+>
+> *Build / config:* drop `spring-boot-jackson2` from `:main`, `:datagenerator`, `:server`, `:api-gateway`. Rename `spring.jackson2.*` → `spring.jackson.*`.
+>
+> *Acceptance criteria:* `./gradlew build` green, `:server:bootRun` and `:api-gateway:bootRun` start cleanly, zero `import com.fasterxml.jackson` in sources.
+>
+> *Risks:* Jackson 3's `JsonMapper` is immutable. Boot 4 BOM may have shifted property prefixes. The XML artifact may have a different group ID.
+>
+> *Reference:* HP-1615 branch, `.claude/plans/spring-boot-4-changes-summary.md`.
+
+**✅ Good (high-level — what + why + the actually non-obvious bits):**
+
+> The Spring Boot 4 upgrade kept Jackson 2 alive via the `{{spring-boot-jackson2}}` shim so Jackson regressions and Boot/Tomcat regressions wouldn't have to be bisected from the same PR. With Boot 4 stable, complete the move to Jackson 3 and drop the shim. Behaviour should be unchanged.
+>
+> Two non-obvious bits to watch:
+>
+> - {{CrawlerConfig}} carries a dual-resolver bridge (Jackson 2 + Jackson 3 `@JsonTypeIdResolver` annotations) added during HP-1615 specifically as a hand-off for this ticket. Jackson 3 becomes the only resolver.
+> - {{HaupiaZookeeperClient}} is the central JSON-serialisation site for ZK. Verify a real round-trip — write a `PreparedSearch` under the shim, read it back under Jackson 3 — green unit tests are not enough on their own.
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No project key resolvable from branch or message | Ask the user; do not guess |
+| Branch ticket has multiple `[A-Z]+` matches or unusual format | Ask which project before drafting |
+| The *what* in the user's request is vague | Ask one focused clarifying question, then draft |
+| Issue type unstated | Default to `Story` or `Escaped Bug` based on the ask (Escaped Bug = defect that escaped release; everything else = Story). Use other types only if the user explicitly names them. |
+| Sub-task without a parent key | Ask for the parent key before drafting |
+| User asks for fields the tool does not accept (component, fix-version, sprint, epic-link) | Surface the limitation; offer to add a label or a comment after creation |
+| `create_jira_ticket` returns an error | Surface the error verbatim; do not retry silently or claim success |
+| Creation succeeds but the user immediately asks for changes the tool can't make | Offer to add a comment or open a follow-up ticket |
+| User says "create the ticket" referring to a draft already in chat | Confirm that draft is the one to file, present full fields verbatim, then wait for explicit approval |
+| Context implies an explicit relationship to another ticket | Propose it as a link (after calling `get_jira_link_types`), shown in the `Links:` block — don't bury it only in the description |
+| A clearly-stated relationship has no matching link type | Don't fabricate one; tell the user and show the available phrases from `get_jira_link_types` |
+| A referenced ticket key is malformed or you're unsure it's real | Skip the link and mention it; do not guess a key |
+| No qualifying link candidates in context | Show `Links: (none — tell me if you want to add one)`; never search JIRA for candidates |
+| `link_jira_issues` errors after the ticket was created | Report it verbatim, keep the created ticket, offer to retry the link |
+
+## Red flags — STOP and reconsider
+
+These thoughts mean the draft is drifting. Catch one, revise before presenting.
+
+| Thought | Reality |
+|---|---|
+| "I should list every affected file so the assignee knows where to look" | The assignee greps the codebase. The ticket is the *why*, not the *where*. |
+| "Acceptance criteria will help reviewers know when it's done" | Most tickets do not need them. The *what* already implies done. Add only if there is a non-obvious done-condition that wouldn't be discovered while doing the work. |
+| "Counts (102 files, 66 imports, 2–3 days) make the scope concrete" | Counts age fast and add no decision value. Estimates are not the AI's call. Drop them. |
+| "Let me include the mechanical steps so the assignee can just follow along" | A bullet list of mechanical steps is a plan. Plans go in `./.claude/plans/`, not JIRA. |
+| "The plan file in `.claude/plans/` already covers this — link to it" | Plans are not committed and not deliverables. Inline the *why* and the non-obvious bits; drop the rest. |
+| "I'll add Out of scope / Risks sections to be thorough" | Those are plan sections, not ticket sections. The default shape has none of them on purpose. |
+| "User said 'looks good' — that's approval" | Strict gate: needs an explicit "create" / "yes, create" / "file it" / "go ahead and create". Anything else means wait. |
+| "I'll re-use the draft the user approved earlier in the session" | Each ticket creation needs its own approval against the exact final fields. Edits invalidate prior approval. |
+| "The description is long because the work is genuinely complex" | Long descriptions almost always indicate plan-leakage, not genuine complexity. Most genuinely complex tickets still fit in under 12 lines of *why* + *what*. |
+| "Let me search JIRA for related tickets to link" | No. Link candidates come only from what's already in context. Never search. |
+| "These two are in the same area, I'll add a relates-to link" | Topical overlap is not an explicit relationship. Link only when the relationship is clearly stated in context. |
+| "I'll suggest a relationship phrase without checking the valid types" | Always call `get_jira_link_types` first; suggest only phrases that match a known type. |
+| "User said 'looks good' — I'll create the ticket and the links" | Strict gate covers links too. Needs an explicit "create" against the presented block. |

package/teams/firstspirit-caas/skills/get-jira-ticket/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: get-jira-ticket
+description: 'Use when the user asks to get, fetch, load, or view a JIRA ticket — phrases like "get HP-1234", "fetch the ticket", "show me this ticket", "what does HP-1234 say". Also triggers on expansion requests within an ongoing conversation: "also get the linked issues", "fetch the attachments too", "expand the blocked-by tickets".'
+---
+
+# Get JIRA Ticket
+
+## Overview
+
+Loads JIRA ticket data into conversation context in a controlled way — fetching the base ticket first, then expanding to linked issues, attachments, or dev info only with explicit user approval. Prevents over-crawling irrelevant information.
+
+**Core principle:** Context is for Claude, summaries are for the user. Fetch eagerly only what is approved; ask before following anything linked.
+
+## When to use
+
+- User asks to get / fetch / load / view a JIRA ticket
+- User asks to expand already-loaded ticket data ("also get the linked issues", "fetch the attachments")
+- Any time JIRA ticket data is needed and has not yet been fetched in this conversation
+
+## When NOT to use
+
+- User wants to update or enrich a ticket — use `specify`
+- User wants to post a comment — use `summarise-for-jira-comment`
+
+## Workflow
+
+### Detect mode
+
+Read conversation history to determine whether this is an **initial fetch** or a **re-invocation** (ticket data already in context).
+
+```
+Ticket already in context?
+├── Yes → Re-invocation mode (see below)
+└── No  → Initial fetch mode (see below)
+```
+
+---
+
+### Initial fetch mode
+
+**1. Identify the ticket key**
+
+- Default: parse `[A-Z]+-\d+` from the current branch name
+- Override: explicit key in user message
+- Unresolvable or ambiguous: ask before proceeding
+
+**2. Fetch base ticket**
+
+Call `mcp__plugin_planetexpress_jira-tools__get_jira_ticket`. Capture all fields: summary, description, status, issuetype, assignee, reporter, priority, linked issues list, attachments list.
+
+**3. Acknowledge and summarise**
+
+Always emit the brief acknowledgment:
+> "Loaded HP-1234 into context."
+
+If the user asked a specific question alongside the fetch (e.g., "get the ticket — is the spec complete?"), answer that question directly from the fetched data. Otherwise, no unprompted dump of ticket fields.
+
+**4. Offer expansions**
+
+Inspect what is available but not yet fetched. If any of the following exist, present them and ask which (if any) to load:
+
+- Linked issues — list them by key + summary; if more than 3, present the list and ask which ones specifically (never "fetch all" as default)
+- Attachments — list names and types; never download without user approval
+- Dev info (branches, commits, PRs) — offer as a single option
+
+If none of the above exist, stop here.
+
+---
+
+### Re-invocation mode
+
+**1. State what is already in context**
+
+Open with a brief note of what is already loaded, including when:
+> "HP-1234 was loaded earlier in this conversation (base ticket + dev info)."
+
+**2. Staleness check**
+
+If the base ticket was fetched in this conversation, note when and ask before re-fetching:
+> "Base ticket was loaded N minutes ago — refresh?"
+
+If the user confirms, re-fetch via `get_jira_ticket` and replace prior data in context.
+
+**3. Fetch new expansions**
+
+Fetch only what the user has now requested or approved. Apply the same per-resource gates as initial fetch mode (linked issues: list first if >3; attachments: show name/type before downloading).
+
+**4. Acknowledge additions**
+
+One-liner per resource fetched:
+> "Added dev info to context — 2 open PRs on feature/HP-1234."
+> "Added linked issue HP-999 (Bug — 'Null pointer in auth flow') to context."
+
+---
+
+## Expansion resources
+
+| Resource | Tool | Gate |
+|---|---|---|
+| Linked issues | `get_jira_ticket` per issue | List all; if >3, ask which ones; never auto-fetch all |
+| Attachments | `download_jira_attachment` per file | Show name + type before each download |
+| Dev info | `get_jira_dev_info` | Single approval covers all dev info |
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No ticket key resolvable | Ask the user; do not guess |
+| Multiple ticket keys in branch name | Ask which one; do not pick |
+| `get_jira_ticket` returns 404 | Confirm key with user; do not continue with bad key |
+| Linked issue returns 404 | Surface it, skip that issue, continue with others |
+| >3 linked issues | Present the list; ask which to fetch; never fetch all by default |
+| Attachment is large or binary | Show file size if available; let user decide |
+| Base ticket already in context, user asks to "get it again" | Staleness check: note when it was loaded, ask "refresh?" before re-fetching |
+| Dev info already fetched, user asks to "get the PRs" | Already in context — surface relevant PR data from existing context rather than re-fetching |
+
+## Red flags — STOP and reconsider
+
+| Thought | Reality |
+|---|---|
+| "I'll fetch all linked issues to be thorough" | Ask which ones. Linked issues can be numerous and unrelated. |
+| "The attachment name is obvious enough — I'll just download it" | Always show name and type first. Downloads are irreversible bandwidth. |
+| "I already have the ticket in context so I'll answer from memory" | Stale context is real. Check when it was loaded; offer refresh if meaningful time has passed. |
+| "User said 'get the ticket' — I'll also pull dev info since it's usually useful" | Only fetch what was asked. Offer expansions after the base fetch. |
+| "There are 8 linked issues — I'll ask 'fetch all?'" | List them individually. "Fetch all" as a default option bypasses the over-crawling guardrail. |