Imported from upex-galaxy/upex-bunkai-tms (.agents/skills/product-management/SKILL.md). Install upstream with npx skills add upex-galaxy/upex-bunkai-tms --skill product-management. Copyright stays with the author (MIT).

Product Management

Orchestrates the continuous product management lifecycle: turning a fresh PRD into an initial Jira backlog, adding new features incrementally as the product evolves, structuring epics, and refining individual stories until they are truly "ready for development". Unlike /project-foundation (one-time, foundational), product management is ongoing work — re-invoke this skill any time backlog work surfaces.

Tool abstraction — hard rule

This skill describes methodology — what to do at each phase. It NEVER hardcodes the how (specific CLI flags, MCP call shapes, REST endpoints). All tool interactions are expressed as [ISSUE_TRACKER_TOOL], [DB_TOOL], [AUTOMATION_TOOL] pseudo-code variables that resolve via AGENTS.md Tool Resolution table. When the AI executes an operation, it loads the matching tool's own skill (e.g. /acli for Jira). Methodology persists across tool changes; this skill must too. See references/jira-operations.md for the operation-by-operation decision table.

When to use

Use this skill whenever you are doing backlog or refinement work after the foundational PRD/SRS exists:

• A new feature or epic needs to be added to the backlog
• A story has rough or ambiguous acceptance criteria that need sharpening
• A story needs INVEST validation or a 3-amigos session before development starts
• You're systematically enumerating edge cases / failure modes for a feature
• You're seeding the very first product backlog from a freshly minted PRD

The skill is reference-driven: each workflow points to a specific reference file with the exact protocol.

This skill does NOT own design, and must not wait for one. A story is written, refined and made ready without any mockup existing. Screens are produced later, per story, at the moment development picks the story up — /sprint-development's design gate routes to /design-system's screen phase then. Do not defer, block or downgrade a story because its screen has not been drawn.

What a UI-touching story DOES owe at creation, where the host project keeps a master design plan, is its §8 US→Screen row — one line naming which screen the story renders into, or naming explicitly that no mockup covers it yet (🔒 mockup-gated). That row is cheap, it is what the design gate reads later, and a story created without one arrives at development already out of compliance. The row is not a mockup and writing it is not designing.

Pre-requisites

• /project-foundation should have produced .context/PRD/ and .context/SRS/ (required for the initial backlog-seed workflow; useful context for all others)
• .agents/project.yaml populated with {{PROJECT_KEY}}, {{ISSUE_TRACKER}}, {{ATLASSIAN_URL}} — these ship with the cloned boilerplate; if missing, clone the full repo
• Atlassian / Jira tooling reachable (Atlassian CLI acli preferred, MCP Atlassian as fallback) for any workflow that writes to Jira

Inputs — read these first

Canonical reading order for any AI starting cold on a product-management workflow. Read in order; stop earlier when the workflow is small enough that later inputs add no signal.

1. .agents/project.yaml — project identity, env URLs, project key, MCP names.
2. .agents/jira-required.yaml — canonical slug catalog (fields + statuses + link types).
3. .agents/jira-fields.json — slug → numeric custom-field-ID mapping.
4. .agents/jira-workflows.json — workflow + transition catalog.
5. .agents/jira-link-types.json — slug → workspace link-type mapping (when present).
6. .context/master-implementation-plan.md — Master Sprint roadmap.
7. .context/PRD/mvp-scope.md — what's in vs out of the MVP.
8. .context/PRD/user-personas.md — actor model.
9. .context/PRD/user-journeys.md — flow-level expectations.
10. .context/SRS/functional-specs.md — FR catalog (source of **Source spec:** references).
11. .context/SRS/non-functional-specs.md — NFRs (perf, security, a11y).
12. .context/business/business-data-map.md — entity graph (source of entity-level dependencies).
13. .context/business/business-feature-map.md — CRUD matrix.
14. .context/business/business-api-map.md — endpoint catalog (auth model, journey breakdown).
15. .context/PBI/epic-tree.md — current backlog state.

Optional inputs. Business maps (12–14) frequently arrive after /business-*-map runs and may be absent at seed time. Proceed without them when missing; surface a missing_input note in the workflow output so a later refinement pass can fill the gap.

Glossary

Two layers share the noun "Sprint". Disambiguate when ambiguity matters; otherwise use the bare term.

• Master Sprint — strategic / architectural grouping (Master Sprint 1–7 typical) sourced from .context/master-implementation-plan.md §5. Locked at PRD time; updates rarely. A single Master Sprint contains multiple Execution Sprints internally.
• Execution Sprint — operational / dependency-driven grouping (Execution Sprint 1, 2, 3 …) produced by references/sprint-sequencing.md via topological sort of the dependency-link graph. Recomputed whenever stories or links change.

Use the bare word Sprint only when the layer is obvious from context. When ambiguity matters, qualify.

Composable Skills (auto-resolved at skill entry)

Run once when this skill is invoked, before any workflow below. Follows the contract in agentic-dev-core/references/skill-composition-strategy.md.

Steps:

1. Read complementary_categories from this skill's frontmatter (issue-tracker, creativity).
2. Resolve via local skill-registry script (scripts/build-skill-registry.ts → cached at .agents/skills/REGISTRY.md). Fallback: scan the session-start system-reminder skill list.
3. For each matched skill, classify tier per strategy doc §2.
4. Apply threshold rule per strategy doc §3.2:
   • T1 / T3 matches → load silently. Cache for the session.
   • T4 matches → ASK user once: "Detected <skill> (T4). Apply for this PM workflow? Y/N". Cache the answer for the session.
5. When dispatching sub-agents (backlog seeding, story refinement, AC enumeration, sprint reporting), inject a ## Composable Skills block per strategy doc §6.2.

Expected matches (illustrative — actual list depends on what the user has installed):

Skip step only if the registry cache is missing AND no session-start skill list is available. When skipped, log skill_resolution: "fallback-inline" plus missing: [<categories with no resolution>] in the result envelope (per strategy doc §3.4).

Session & Dispatch

Orchestration & Session contracts: this skill follows ./orchestration-doctrine.md (mandatory subagent dispatch — main thread is command center) AND ./session-management.md (Phase 0 resume check, plan-first persistence at .session/<skill-slug>/<scope>/, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional.

Session management applies only to workflows A, B, C below. Short, single-actor, non-interruptible workflows opt out:

When the user invokes any of D / E / F / G / H, do NOT create a .session/product-management/ directory and do NOT run Phase 0. Skill the carve-out is documented here so users don't expect a session directory for those workflows.

Phase 0 — Resume check (MANDATORY for A / B / C only, inline)

Before dispatching any subagent or invoking workflow A / B / C below, run the resume contract from agentic-dev-core/references/session-management.md §4:

1. Resolve <scope> for this invocation:
   • Workflow A → <scope> = seed
   • Workflows B / C → <scope> = <epic-slug> (kebab-case epic identifier resolved from user input)
2. Check whether .session/product-management/<scope>/progress.md exists.
3. If it does NOT exist → proceed to Phase 1 (write plan.md).
4. If it DOES exist:
   1. Read .session/product-management/<scope>/plan.md in full.
   2. Read the tail of .session/product-management/<scope>/progress.md (last ~3 phase entries).
   3. Surface to the user: plan Goal (one sentence), last completed phase + timestamp, next planned phase, any blocking notes.
   4. Offer three options and WAIT for input: resume / restart (archive current dir to .session/.archive/<YYYY-MM-DD>-product-management-<scope>-aborted/) / abort.

Phase 0 is inline — no subagent dispatch.

Phase 1 — Write plan.md (A / B / C only)

After Phase 0 confirms no prior session exists, write .session/product-management/<scope>/plan.md per the schema in agentic-dev-core/references/session-management.md §6:

• Frontmatter: topic_key: session/product-management/<scope>/plan, skill: product-management, scope: <scope>, status: draft, capture_prompt: true.
• Body sections (fixed H2 order): ## Goal · ## Inputs (PRD / SRS paths, Jira project key, existing epic list when applicable) · ## Approach · ## Phase breakdown (per workflow — A enumerates epics-to-seed; B routes single-story / full-epic / multi-epic; C decomposes epic into stories) · ## Risks & open questions · ## Verification checklist · ## Cross-references (cite .context/PBI/<scope>/ epic + story files).

Dispatch: inline draft for B / C when scope is one epic; Single planner subagent for A when the PRD has 5+ epics to seed.

After plan.md is written and the user approves, transition status: draft → approved and proceed to the workflow's first execution phase.

Progress checkpoint: per-epic-created (A), per-story-added (B), per-section-of-epic decomposed (C). The orchestrator appends an entry to .session/product-management/<scope>/progress.md per agentic-dev-core/references/session-management.md §7 at each checkpoint.

Story title format (canonical — applies to every US summary)

The User Story summary (Jira title) is NOT the As a … I want to … so that … sentence. That full sentence is too long for board cards and buries the action between persona and benefit. The summary uses this scannable format; the canonical sentence lives in the description ## User story section instead.

{Feature} | {Action}

• {Feature} — 1–3 words, Title Case noun phrase. The abbreviated feature name, finer-grained than the epic. The epic = the module (holds several features); the prefix = the feature this US belongs to. Sibling stories of the same feature SHARE the prefix. A feature may be one US, a whole epic, or a feature split across several US — the shared prefix is what makes the split traceable.
• | — space, pipe, space (literal separator).
• {Action} — the I want to … clause rewritten as a base-form verb phrase (imperative/infinitive). DROP the persona (As a …) and the benefit (so that …); KEEP scenario qualifiers (quickly, from a failing run step, in a chosen environment). Sentence case, no trailing period, ~3–9 words.

TMS- domain-collision prefix. When the product under development is itself a test/issue management system (or any tool whose own entities share names with agile/QA vocabulary), a {Feature} that names a product domain entity collides with the same word at the meta level — a story titled User Stories | … is ambiguous (the backlog, or the product feature?). Prefix such entity features with the project-domain tag TMS- (or the project's equivalent short tag): User Story → TMS-US, Acceptance Criteria → TMS-AC, Module → TMS-Module, Workspace → TMS-Workspace, Project → TMS-Project, ATC → TMS-ATC, Test → TMS-Test, Run → TMS-Run, Defect → TMS-Defect. The sub-feature qualifier stays after the entity (TMS-ATC Builder, TMS-Run Execution). Cross-cutting / non-entity features stay PLAIN (Authentication, Markdown Editor, Jira Import).

Hard rules: English always (repo artifact). Total summary ≤ ~80 chars (board cards truncate beyond). No FR-/issue-key/spec prefix (I2). Persona + benefit never in the title — only in the description.

Epics keep their own convention: noun-phrase module titles, NO pipe, NO verb (e.g. Tenancy & Identity, Bugs & Defect Heatmap). The epic = module; the US prefix = the abbreviated feature inside that module.

Pre-flight — voice & format gate (MANDATORY before every Jira write)

This is a force-function checklist. Run it in working memory immediately before any [ISSUE_TRACKER_TOOL] create / edit that touches summary, description, {{jira.acceptance_criteria}}, {{jira.scope}}, {{jira.out_of_scope}}, {{jira.business_rules_specification}}, {{jira.workflow}}, or {{jira.story_points}}. If any item fails, fix the draft BEFORE the write — never publish and patch.

• Persona (I19) — the As a clause names a real entity from .context/PRD/user-personas.md. Generic ("the user", "the customer", "the system") → STOP, ask the user or surface as gap.
• Voice (I15) — no API endpoint paths, no HTTP status codes (201/422/403), no DB table or column names, no error-code identifiers (VALIDATION_ERROR, FOO_NOT_FOUND), no framework or library names (Zod, Supabase, Next.js), no transaction/locking patterns, no internal algorithms appear in {{jira.acceptance_criteria}} / {{jira.scope}} / {{jira.out_of_scope}} / {{jira.workflow}}. Exception: persona is an API consumer (DevEx / agent / headless client) — then endpoint paths and response shapes ARE part of their observable UX.
• AC format (I17) — every Gherkin scenario for {{jira.acceptance_criteria}} is wrapped in a fenced ```gherkin code block (Jira ADF renders this as monospaced + syntax-highlighted; unfenced AC is unreadable in the Jira UI). On re-format passes of existing AC, rewrite the field in full to apply the fence.
• ADF visual structure — where a field's content is naturally mappable (parallel data, option comparisons, multi-level hierarchy, business-rule → boundary grids), structure it per ../acli/references/adf-authoring-style.md (tables / nested lists / panels) instead of flat prose. Richness with purpose, never decoration. Field hard-rules win: AC stays fenced Gherkin (I17) — never replace a mandated shape with a table.
• Story Points (I16) — {{jira.story_points}} is left EMPTY unless the user explicitly asked for estimation in the current session ("estimate this", "size this story", "story points", or equivalent). If opted-in: Fibonacci 1, 2, 3, 5, 8; 13+ is a smell → split.
• No-duplication (I3) — the description body contains no ## Acceptance Criteria, ## Scope, or ## Out of Scope H2 sections. Those live exclusively in their custom fields.
• Source spec (I2) — if the story maps to a single FR, the description body starts with **Source spec:** FR-XXX as its first line. If no FR maps cleanly, omit the line — never invent or use N/A.
• Summary nomenclature (I2) — the summary contains no functional-spec or issue-key prefix (e.g. patterns like FR-NNN followed by an em-dash, or <PROJECT>-NNN followed by an em-dash). The Jira issue key is the only identifier that belongs in the summary.
• Title format (I20) — the story summary is {Feature} | {Action} (see §Story title format). The As a … I want to … so that … sentence is NEVER the summary — it lives only in the description ## User story section. Persona and benefit do not appear in the title; the Action is the I want to … clause as a base-form verb phrase. Domain-entity prefixes carry the TMS- (project-domain) prefix.
• No-invent (I5) — every AC, Scope item, OOS item, business rule traces back to a concrete source (PRD, SRS, business map, explicit user input). Missing source → report gap, halt that field, continue with the rest.
• Glossary alignment (I21) — every domain entity/process/state name in summary, description, and {{jira.acceptance_criteria}} matches .context/business/domain-glossary.md; no anti-glossary banned terms appear. A term missing from the glossary → flag gap, do not invent terminology mid-story.

After the write, before moving to the next field/story:

• AC render verification (I17) — confirm the Jira UI renders the AC field as a monospace code block with Gherkin highlighting (open the issue or rely on the user's visual confirmation when running in autonomous mode).
• Link direction verification (I8) — if any link was created in this step, run the post-create direction check from references/dependency-linking.md §Procedure step 6 before declaring the operation complete.

Main workflows

A. Initial backlog seeding (one-time, from PRD)

When you have a fresh PRD/SRS and zero issues in Jira, generate the initial backlog tree (epics + their foundational stories) by creating the issues in Jira, then materialize the local read-only cache under .context/PBI/ via the sync script.

Read references/product-backlog-seed.md.

Output: epics + foundational stories created in Jira under {{PROJECT_KEY}}, then bun run jira:sync-issues pull materializes .context/PBI/epic-tree.md + the canonical .context/PBI/epics/EPIC-<KEY>-<slug>/ tree (epic + per-story folders). Local .md is a read-only cache — never hand-written. Topic_key for memory notes: per-epic pbi/{epic-slug}/epic; per-story pbi/{ticket}/spec. See agentic-dev-core/references/topic-key-conventions.md.

B. Incremental feature addition (continuous)

When a new feature emerges mid-flight (PO ask, market opportunity, post-MVP work, customer feedback). The reference first analyzes complexity — single story, full epic, or multi-epic — then routes accordingly.

Read references/add-feature.md.

Output: new epic or stories appended to the backlog, with the complexity decision documented.

C. Epic creation (from scratch or from add-feature workflow)

When you need to formally structure a new epic — naming, scope boundaries, decomposition into stories, traceability back to PRD goals.

Read references/epic-creation.md.

Output: Epic created in Jira (with child stories) under {{PROJECT_KEY}}, then bun run jira:sync-issues pull --epic <KEY> materializes the canonical .context/PBI/epics/EPIC-<KEY>-<slug>/epic.md + decomposed child-story folders as a read-only cache. Topic_key for memory notes: pbi/{epic-slug}/epic (UPSERT semantics; see agentic-dev-core/references/topic-key-conventions.md).

D. Story refinement (per story)

When a story exists in Jira but is not yet "ready for development". Validates INVEST, optionally runs a 3-amigos session, ensures story slicing is appropriate, and confirms the ready-for-development checklist passes.

Read references/story-refinement.md.

Output: refined story with INVEST validated, optional 3-amigos notes appended, ready-for-dev checklist confirmed.

E. AC quality refinement (per story)

When a story has rough acceptance criteria — vague conditions, missing data, no error scenarios, no boundaries — and you need to sharpen them into concrete Gherkin scenarios (Scenario / Given–When–Then).

Read references/acceptance-criteria.md.

Output: refined AC in Gherkin with concrete data, error scenarios, and boundary scenarios; ambiguities surfaced as open questions if not resolvable from PRD/SRS. Persists at .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/spec.md with topic_key pbi/{ticket}/spec. See agentic-dev-core/references/topic-key-conventions.md.

F. Edge-case enumeration (per feature/epic)

When designing or refining a feature and you need to systematically enumerate failure modes, boundary conditions, integration risks, and unusual user paths. Includes the decision rule for what becomes AC vs what stays as a test-only concern.

Read references/edge-cases-enumeration.md.

Output: cataloged edge cases with criticality + decision (high-criticality + clearly-defined behavior → promote into AC; otherwise → test-only, hand off to QA). Persists at .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/edge-cases.md with topic_key pbi/{ticket}/edge-cases. See agentic-dev-core/references/topic-key-conventions.md.

G. Sprint reporting (read-only PM snapshot)

When the user wants a development-oriented view of the current sprint and backlog — epics, stories, PRs grouped by status (BLOCKED, In Progress, In Review, Ready For Dev, Backlog, Done) with metrics and alerts. This is read-only — it does not change Jira state, does not create issues, and does not write to .context/. Its job is to gather state from [ISSUE_TRACKER_TOOL] (and optionally gh for PRs) and render a structured markdown report in the conversation.

Read references/sprint-report.md.

Output: a markdown sprint report rendered inline (epics + stories + PRs + status summary + per-epic progress + alerts). Not persisted by default — persist only if the user explicitly asks.

H. Sprint sequencing (topological execution order)

When the user asks "what do we work on first?", "qué historias trabajamos primero", "execution order", "sprint plan", or "topological order". Compute Execution Sprints by topologically sorting the dependency-link graph across the in-scope epics + stories.

Read references/sprint-sequencing.md.

Output: invoke /dev-roadmap to write the execution-sprint sort to .context/dev-roadmap.md §4 (which also preserves the hand-authored backbone/edges/gates) + an inline summary table. This workflow DELEGATES the write to /dev-roadmap; it no longer authors a file itself. Session-managed: NO (one-shot derivation, no plan.md required).

Archive (A / B / C only)

On successful completion of workflow A / B / C (Verification checklist from the workflow's plan.md passes), the orchestrator runs Archive per agentic-dev-core/references/session-management.md §8 — moves .session/product-management/<scope>/ to .session/.archive/<YYYY-MM-DD>-product-management-<scope>/ and calls mem_session_summary with the archive path included so future mem_search calls can navigate back. Workflows D / E / F / G never write .session/ directories and therefore have nothing to archive.

Specific tasks — which reference to read

Optional: Delta Specs Pattern

For projects with concurrent devs on the same feature, compliance/audit requirements, or capabilities that need an explicit history of behavioral change, an opt-in formal change-tracking pattern is available. Instead of editing acceptance criteria in place on each story, you maintain:

• Source-of-truth specs at .context/PBI/specs/{capability}/{feature}.md (canonical, always-current behavior — RFC 2119 + Gherkin)
• Delta specs per change at .context/PBI/epics/EPIC-<KEY>-<slug>/stories/STORY-<KEY>-<slug>/spec.md with explicit ## ADDED Requirements, ## MODIFIED Requirements, and ## REMOVED Requirements sections
• Archive process that merges deltas back into the source-of-truth on story close and moves the change folder under .context/PBI/archive/YYYY-MM-DD-{ticket}/

See references/delta-specs.md for the full pattern: when to adopt it, requirement format, the copy-full-then-edit rule for MODIFIED requirements, the archive protocol, and migration guidance.

Default flow remains in-place AC editing (lower overhead, fits solo developers and small teams). Adopt delta specs only when one of the conditions in the reference document actually holds — the overhead is real.

Hand-offs

When PM artifacts are ready, the natural downstream skills are:

• Per-story implementation → /sprint-development (planning → code → review → deploy loop)
• TDD on a single function → /unit-testing (composable inside /sprint-development)
• Formal QA test cases, exploratory testing, automation, regression → out of scope here; handled by a separate QA workflow

Anti-patterns — NEVER do these

• I1. NEVER hardcode customfield_NNNNN IDs in skill or AI output. Resolve via {{jira.<slug>}}.
• I2. NEVER prefix story summaries with FR-XXX —. Use **Source spec:** FR-XXX as the first body line.
• I3. NEVER copy AC / Scope / Out-of-Scope content into the description. Those live exclusively in their custom fields.
• I4. NEVER let two stories in the same epic share a literal Scope bullet. Surface as overlap_alert and ask the user to resolve.
• I5. NEVER invent acceptance criteria, scope items, or business rules. Source must be PRD / SRS / business map / explicit user input. If missing → report gap, halt that field, continue with the rest.
• I6. NEVER batch multiple ADF custom fields in a single MCP update call. Split per field, or pre-convert with md-to-adf.ts.
• I7. NEVER nest inline `code` inside **bold** markdown destined for ADF — the converter combines incompatible marks and Jira rejects HTTP 400.
• I8. NEVER create stories without immediately running the dependency-linking phase. Local declarations are not enough; Jira links must exist.
• I9. NEVER hardcode acli, mcp__atlassian__, or REST URL examples in this skill. Use [ISSUE_TRACKER_TOOL] pseudo-code. The tool skill owns the syntax.
• I10. NEVER use "Wave" terminology. Use "Sprint" (or "Master Sprint" / "Execution Sprint" when ambiguity matters).
• I11. NEVER skip sprint-sequencing after creating multiple linked stories.
• I12. NEVER hardcode link-type names ("Dependencies", "Blocks", "Relates"). Use {{jira.link_types.<slug>}}.
• I13. NEVER use Relates for ordering-sensitive dependencies. Symmetric → direction is lost. Use Dependencies (or flag fallback explicitly as degradation).
• I14. NEVER ignore cycle detection in sprint-sequencing. A cycle in the dependencies graph is a bug — halt and report.
• I15. NEVER include implementation surface in {{jira.acceptance_criteria}}, {{jira.scope}}, {{jira.out_of_scope}}, or {{jira.workflow}}. Disallowed surface: API/endpoint paths, HTTP status codes, DB table/column names, error-code identifiers (e.g. VALIDATION_ERROR), framework or library names, transaction/locking patterns, internal algorithms. Those describe HOW; AC/Scope/Workflow describe WHAT the persona observes/does/receives. Implementation belongs in the impl-plan generated by /sprint-development. {{jira.business_rules_specification}} tolerates domain rules (boundaries, role gates, retry semantics, audit guarantees) but NOT internal algorithms. Exception: when the persona is an API consumer (DevEx, integration agent, headless client), endpoint paths and response shapes ARE part of their observable UX. Heuristic: if the criterion stays true after a stack swap → business voice; if a stack swap breaks it → implementation, rewrite.
• I16. NEVER populate {{jira.story_points}} on create or edit by default. Story Points stay EMPTY unless the user explicitly requests estimation in the current session ("estimate this", "size this story", "story points", or equivalent in the user's language). Rationale: PO/BA role does not estimate; estimation belongs to the team that will build the work (Design + Dev + Test). When opted-in by the user, use Fibonacci (1, 2, 3, 5, 8); 13+ is a smell → split instead.
• I17. NEVER write {{jira.acceptance_criteria}} as plain text. Every scenario MUST be wrapped in a fenced ```gherkin code block. Applies on initial create AND on every edit/re-format pass. Reason: Jira ADF renders the fenced block as monospaced + syntax-highlighted, which is the only readable shape for Given/When/Then in the Jira UI. When refining EXISTING AC that was written unfenced, rewrite the field in full to apply the fence.
• I18. NEVER create or edit a story (or epic) without first running an active dependency discovery pass against the current backlog graph (.context/PBI/epic-tree.md + live Jira link graph + .context/business/business-data-map.md when present). Default state is "no global/infrastructural dependencies surface as story links" — generic prerequisites (auth exists, DB exists, framework is set up) are filtered out as noise. Only feature-level, observable, explicit dependencies become candidate links. Output: a (from, to, source-of-decision) matrix surfaced to the user for confirmation BEFORE writing any Jira link. Passive "only link if obviously needed" is rejected — discovery is an active step.
• I19. NEVER use generic actors ("the user", "the customer", "the system") in the As a line of a user story. The persona MUST resolve to a named entity in .context/PRD/user-personas.md. If the matching persona is absent → surface as gap, ask the user, never invent.
• I20. NEVER write the As a … I want to … so that … sentence as the story summary. The summary MUST be {Feature} | {Action} (see §Story title format); the full sentence lives ONLY in the description ## User story section. Persona and benefit NEVER appear in the title. Domain-entity feature prefixes that collide with agile/QA vocabulary carry the TMS- (project-domain) tag; cross-cutting features stay plain. Epics keep noun-phrase titles (no pipe, no verb).
• I21. NEVER publish Jira content whose domain entity/process/state names diverge from .context/business/domain-glossary.md, and NEVER use a term its anti-glossary bans — use the prescribed replacement. A needed term missing from the glossary → surface as gap for the PM to add per the glossary's change protocol; never invent terminology mid-story.

Variables consumed

This skill uses standard .agents/project.yaml variables resolved at runtime:

• {{PROJECT_KEY}} — Jira project key (e.g., MYM, UPEX)
• {{ISSUE_TRACKER}} — issue tracker name (typically Jira)
• {{ATLASSIAN_URL}} — workspace URL

In addition, every Jira-side identifier (custom field, status, link type) is resolved via slug indirection. .agents/jira-required.yaml is the canonical slug catalog:

• {{jira.<slug>}} — custom-field IDs resolved via .agents/jira-required.yaml + .agents/jira-fields.json. Examples: {{jira.acceptance_criteria}}, {{jira.scope}}, {{jira.out_of_scope}}, {{jira.business_rules_specification}}, {{jira.workflow}}, {{jira.weblink}}, {{jira.mockup}}.
• {{jira.statuses.<slug>}} — default statuses for newly-created items. Examples: {{jira.statuses.epic_default}} (default literal Planning), {{jira.statuses.story_default}} (default literal Shift-Left QA).
• {{jira.link_types.<slug>}} — link-type names resolved via .agents/jira-link-types.json. Sub-fields: .outward, .inward, .fallback. Examples: {{jira.link_types.dependencies}}, {{jira.link_types.dependencies.outward}} (depends on), {{jira.link_types.dependencies.inward}} (is dependency for), {{jira.link_types.dependencies.fallback}} (relates).

If unset, clone the full boilerplate — these foundation files ship with the repo.

Notes

• Refinement is a continuous activity, not a one-time gate. Re-invoke this skill any time AC questions emerge, edge cases surface during design, or a story is found to violate INVEST mid-sprint.
• The 3-amigos protocol is optional in story refinement — recommended for stories larger than ~5 SP, integration-heavy stories, or anything touching unfamiliar areas of the system.
• Edge cases that don't make it into AC are not lost — they live in QA test cases (out of scope here).
• Orchestration: for parallel research tasks (e.g., competitive analysis on a feature, prior-art review, persona impact study), dispatch via the briefing template at .agents/skills/agentic-dev-core/references/briefing-template.md.