bigeasyfreeman/skills/jira-ticket-creation

Skill: JIRA Ticket Creation

Creates structured JIRA tickets from Build Brief task breakdowns. Produces tickets with acceptance criteria, constraints, architecture pattern references, and linked failure modes that autonomous coding agents can execute against.

---

Trigger

Activated after the engineer approves the Build Brief. Consumes the schema-validated Build Brief, especially task breakdown, phased plan, and each task's applicability/verifier contract.

Emitter Contract Alignment

This skill is a work-item emitter and must conform to docs/specs/emitter-contract.md. Suppressed sections do not become filler ticket content. Every mutation requires contract_version, idempotency handling, and permission logging.

Local MCP Model

ADLC does not ship a JIRA client. This skill targets a locally installed MCP provider that can search, create, update, and relate JIRA artifacts. Repo configuration resolves the provider name and binds the logical capabilities from the shared emitter contract to the provider's actual tool names.

Input Contract

{
  "contract_version": "1.x",
  "adlc_mode": "prd_only | decompose_only | prd_and_decompose",
  "build_brief_id": "string",
  "feature_name": "string",
  "owner": "string",
  "jira_config": {
    "project_key": "string",
    "epic_name": "string (created if not exists)",
    "sprint_id": "string (optional, for Phase 1 tasks)",
    "board_id": "string",
    "issue_type_mapping": {
      "backend": "Story | Task",
      "frontend": "Story | Task",
      "infra": "Task",
      "observability": "Task"
    }
  },
  "mcp_provider": {
    "server_name": "string",
    "capability_bindings": {
      "search_by_metadata": "string",
      "upsert_parent_artifact": "string",
      "upsert_artifact": "string",
      "apply_artifact_metadata": "string",
      "link_dependencies": "string (optional)"
    }
  },
  "task_breakdown": {
    "backend": [],
    "frontend": [],
    "infra": [],
    "observability": []
  },
  "phased_plan": {
    "phase_1": [],
    "phase_2": [],
    "phase_3": []
  },
  "architecture_patterns": {},
  "enterprise_readiness_contract": {},
  "failure_modes": []
}

Every emitted ticket must preserve the task's artifact_type, task_classification, decision_contract, verification_spec, reference_impl, explicit reuse instructions, tech_debt_boundaries, compatibility_contract, construct_map_refs, paved_road_refs, intent_contract_refs, production_invariant_coverage, implementation_interface_contract, productionization_gate, slop_quality_gate, Loop Contract refs (loop_contract_path, loop_action_path, loop_maturity_report_path), evidence_responsibilities, definition_of_done, and any active overlay expectations from the brief's applicability_manifest. If the brief includes prerequisite debt-paydown work or deferred-cleanup notes, those must remain visible in the emitted ticket. The top-level enterprise_readiness_contract must remain visible from the epic and referenced by validation tickets. Suppressed sections do not become filler ticket content. Unsupported claims and non-sequitur guardrail lines do not become ticket scope.

Mixed Acceptance Criteria Shapes

Task acceptance criteria may arrive as strings or structured objects.

Extraction rules:

• If an item is an object, read its .then field for the visible acceptance-criteria text.
• If an item is a string, use the string directly.
• Preserve any upstream id and measurable_post_condition when present; do not flatten structured items into prose that loses them.

Output Contract

{
  "contract_version": "1.0.0",
  "epic": {
    "key": "PROJ-123",
    "url": "string",
    "title": "string"
  },
  "tickets": [
    {
      "key": "PROJ-124",
      "url": "string",
      "title": "string",
      "artifact_type": "scope_lock_epic | decision_gate | implementation_task | validation_task",
      "blocks_implementation": false,
      "type": "Story | Task | Sub-task",
      "area": "backend | frontend | infra | observability",
      "phase": 1,
      "assignee": "string (if provided)",
      "story_points": "number",
      "linked_failure_modes": ["FM-001"],
      "idempotency_key": "BRF-123:jira:TASK-7:create",
      "sprint_id": "string (if Phase 1)"
    }
  ],
  "dependency_links": [
    {
      "from": "PROJ-124",
      "to": "PROJ-125",
      "type": "blocks | is_blocked_by | relates_to"
    }
  ],
  "summary": "string"
}

Behavior

1. Create Epic

Create an epic for the feature:

• Title: [Feature Name] - [Target First Slice Date]
• Description: Build Brief Section 1 (What Changes) + link to the configured documentation parent page
• Labels: adlc, [segment], [phase]
• Fix version: target release (if configured)

2. Create Tickets from Task Breakdown

For each artifact in the Build Brief task breakdown, create a ticket unless adlc_mode is prd_only:

Title format: [Area] [Verb] [Specific Deliverable]

• Good: [BE] Add POST /api/v1/widgets endpoint with validation
• Bad: Set up the API

Emitter rules:

• Preserve artifact taxonomy. scope_lock_epic is context only, decision_gate blocks implementation, implementation_task is executable coding work, and validation_task owns evidence and final readiness proof.
• Do not create executable implementation tickets when decision_contract.status is unresolved; create or preserve the blocking decision gate instead.
• Stop before mutation if dependencies contain unresolved aliases.
• Keep the first sentence concrete and behavior-first.
• Preserve positive invariants from the brief before negative bans.
• Do not emit defensive comparison lines unless they are grounded by the brief's contamination or prior-failure evidence.

Description template:

h2. Task
[Task description from brief — self-contained, no references to "the spec" or "as discussed". Lead with the user/system behavior that changes, then the architecture details.]

h2. Artifact Type
* Type: [scope_lock_epic | decision_gate | implementation_task | validation_task]
* Executable: [yes/no]
* Blocks Implementation: [yes/no]

h2. Decision Contract
* Type 1 decision: [true/false]
* Status: [not_applicable | unresolved | resolved]
* Owner: [name]
* Deadline: [date or not_applicable]
* Resolution: [resolved decision or exact question to answer]

h2. Acceptance Criteria (Given/When/Then)
{panel:title=Done When}
* Given [precondition], When [action], Then [expected outcome]
* Given [precondition], When [action], Then [expected outcome]
* Given [precondition], When [action], Then [expected outcome]
{panel}

h2. Architecture Pattern
Follow: [pattern name] per [file path reference]
Reference implementation: [file path — the agent should study this file before coding]

h2. Reuse / Existing Patterns
* Reuse: [existing service/helper/pattern to extend]
* Do Not Reimplement: [existing helper/service/pattern that must not be duplicated]

h2. Constraints
* Must: [must do items]
* Must Not: [must not do items]
* Escalate If: [escalation triggers]
* Task Classification: [feature | bugfix | build_validation | lint_cleanup | refactor | infra | docs | security]

h2. Tech Debt / Cleanup Boundaries
* Prerequisite debt: [blocking debt to pay down first, or "none"]
* Deferred debt: [allowed deferral with owner, or "none"]
* Why deferral is safe: [brief justification when deferred debt exists]

h2. Compatibility Contract
* Backward compatibility: [existing consumers and behavior preserved]
* Forward compatibility: [future phases accommodated without premature lock-in]
* Migration or rollout: [feature flag, migration, rollout, rollback, or N/A]

h2. Scalable AI Code Primitives
* Construct map refs: [affected constructs, relationships, validation surfaces]
* Paved-road refs: [approved reference paths or explicit no_paved_road_found]
* Intent contract refs: [behavior/why/constraints/non-goals source]
* Production invariant coverage: [identity/auth/tenancy/data/persistence/ordering/idempotency/retry/observability/etc. status + evidence]

h2. Implementation Interface Contract
* Reuse: [existing module, schema, CLI, workflow, provider, or helper]
* Consumes: [input, state, config, artifact, event, or dependency]
* Emits: [output, state update, artifact, event, side effect, or evidence]
* Minimum fields: [required fields and semantic constraints]
* Invariants: [compatibility, idempotency, privacy, rollback, or data-integrity rules]
* Integration points: [path, command, schema, provider, or runtime boundary]
* Validation gates: [test, schema, command, smoke check, or review gate]

h2. Productionization Gate
* Claim: [production support claim]
* Coverage State: [unsupported | evidence_only | monitor_only | not_yet_ga | governed | production_ready]
* Validation evidence: [tests, schemas, commands, smoke checks, dashboards, approvals]
* No-Overclaim: [what this ticket does not prove or support]
* Reliability failure modes: [known failure modes and mitigations]
* Operational readiness: [owner, rollback path, runbook/alerting/dashboard/SLO refs]
* Security/privacy posture: [redaction, secrets, retention, audit evidence]

h2. Slop Quality Gate
* Applicability: [required | not_applicable]
* Reason: [why generated-output quality gate is active or not applicable]
* Mode: [code | content | product_output | agent_output | mixed]
* Metrics: [exact match, schema validity, semantic similarity, rubric score, test strength, or task-specific validator]
* Threshold: [0 to 1]
* Eval cases: [case IDs or inline cases]
* Baseline score: [number or N/A]
* Regression tolerance: [number or N/A]
* Failure action: [block | revise | human_approval | monitor]
* Case promotion sources: [human_edit, council_rejection, runtime_failure, production_sample, incident, support_ticket, analytics_drop, other]

h2. Dependencies
* Depends on: [task IDs or "none — parallelizable"]
* Blocks: [task IDs or "none"]

h2. Verification Contract
* Primary verifier: [test | command | reproducer] — [target]
* Expected before change: fail
* Expected after change: pass
* Target files: [exact files the verifier must cover]
* Expected failure mode: [pre-change failure signal]
* Verifier phrasing: [feature = intended behavior; bugfix/build/lint = direct reproducer or command]
* Overlay checks: [security/observability/performance only when active]

h2. Evidence Responsibilities
* [tests/logs/screenshots/audit/deploy evidence this ticket owns]

h2. Definition of Done
* [binary completion check]

h2. Agent Instructions
[Self-contained context — everything a coding agent needs to implement this task without searching]
* Files to modify: [explicit file paths]
* Files to create: [explicit file paths]
* Pattern to follow: [pattern name + reference file]
* Test file to update: [test file path]

h2. Failure Modes
|| ID || Failure || Likelihood || Prevention ||
| [FM-ID] | [description] | [L/M/H] | [prevention measure] |

h2. Estimated Hours
[X]h -- decompose into sub-tasks if > 2h

h2. Links
* Build Brief: [Confluence or Notion link]
* PRD: [link]

3. Map Tasks to Phases and Parallel Groups

• Phase 1 tasks: add to current sprint (if sprint_id provided), label phase-1
• Phase 2 tasks: label phase-2, add to backlog
• Phase 3 tasks: label phase-3, add to backlog

Parallel execution groups: Tasks flagged as Parallel: Yes with no dependencies between them are grouped and labeled parallel-group-N. This signals to coding agent orchestration that these tasks can be assigned to multiple agents simultaneously.

• Label independent tasks: parallelizable
• Create a JIRA board filter for parallel groups
• Add a comment to each parallelizable task: "This task has no dependencies and can be assigned to an independent coding agent."

4. Create Dependency Links

Analyze task descriptions and phase ordering to create JIRA links:

• Infra tasks that must complete before backend tasks: blocks relationship
• Backend tasks that must complete before frontend tasks: blocks relationship
• Observability tasks that depend on backend endpoints: is_blocked_by
• Cross-cutting tasks: relates_to

5. Create Sub-tasks for Large Tasks

If estimated hours > 2h, decompose into sub-tasks:

• Each sub-task ≤ 2h
• Sub-tasks inherit the parent's acceptance criteria subset
• Sub-tasks inherit the parent's architecture pattern reference

6. Attach Failure Mode Cross-Reference

For each failure mode in the roll-up (Section 11):

• Find the task(s) that would prevent or detect it
• Add the failure mode ID to those tickets
• Create a linked "Risk" issue type if the failure mode is P0 or P1

7. Set Custom Fields (if configured)

| Field | Source | Value | |-------|--------|-------| | Decision Type | Phase 2 decisions | Type 1 / Type 2 | | On-Call Rotation | Active observability/operations section | rotation name | | Service Owner | Active observability/operations section | team name | | Architecture Pattern | Section 2 | pattern name | | SLO Target | Active observability/performance section | availability target |

Mixed Acceptance Criteria Quality Gates

• [ ] Mixed acceptance-criteria handlers read .then from objects and raw text from strings
• [ ] Any acceptance-criteria id present upstream is preserved in the emitted ticket
• [ ] Any measurable_post_condition present upstream is preserved in the emitted ticket or linked metadata
• [ ] Verification contract fields survive decomposition without being weakened
• [ ] Reference implementations and explicit reuse instructions survive decomposition without being weakened
• [ ] Blocking or deferred tech-debt notes survive decomposition with sequencing context intact

Required Local MCP Capabilities

ADLC expects a locally installed MCP provider. Provider tool names may differ; repo configuration maps them to the logical capability set. The payloads below are normalized examples, not a requirement that the provider expose these exact tool names.

Logical operation: create work items from brief

{
  "name": "create_tickets_from_brief",
  "description": "Create JIRA epic and tickets from Build Brief task breakdown",
  "inputSchema": {
    "type": "object",
    "properties": {
      "build_brief": {
        "type": "string",
        "description": "Full Build Brief markdown or Section 8 + Section 7"
      },
      "contract_version": {
        "type": "string",
        "description": "Expected contract version range, e.g. 1.x"
      },
      "project_key": {
        "type": "string",
        "description": "JIRA project key"
      },
      "sprint_id": {
        "type": "string",
        "description": "Sprint ID for Phase 1 tasks (optional)"
      },
      "dry_run": {
        "type": "boolean",
        "default": true,
        "description": "If true, show tickets without creating"
      }
    },
    "required": ["contract_version", "build_brief", "project_key"]
  }
}

Logical operation: update work items from brief

{
  "name": "sync_tickets_with_brief",
  "description": "Update existing JIRA tickets when the Build Brief changes",
  "inputSchema": {
    "type": "object",
    "properties": {
      "build_brief": {
        "type": "string",
        "description": "Updated Build Brief markdown"
      },
      "contract_version": {
        "type": "string",
        "description": "Expected contract version range, e.g. 1.x"
      },
      "epic_key": {
        "type": "string",
        "description": "Existing JIRA epic key"
      }
    },
    "required": ["contract_version", "build_brief", "epic_key"]
  }
}

Provider Resolution Example

{
  "server_name": "jira-local-mcp",
  "capability_bindings": {
    "search_by_metadata": "issues.searchByMetadata",
    "upsert_parent_artifact": "issues.upsertEpic",
    "upsert_artifact": "issues.upsertIssue",
    "apply_artifact_metadata": "issues.applyBoardSprintAndLabels",
    "link_dependencies": "issues.linkDependency"
  }
}

Quality Gates

• [ ] Every task in Section 8 has a corresponding JIRA ticket
• [ ] Ticket bodies preserve artifact_type, decision_contract, compatibility contracts, construct-map refs, paved-road refs, intent refs, production invariant coverage, evidence responsibilities, and Definition of Done.
• [ ] Scope-lock epics are context-only and do not carry executable file-change instructions.
• [ ] Decision-gate tickets block dependent implementation tickets until resolved.
• [ ] Validation tasks are emitted automatically for decomposition-mode briefs and reference the enterprise readiness contract.
• [ ] Unresolved dependency aliases fail before any external mutation.
• [ ] All tickets have acceptance criteria (not empty)
• [ ] All tickets reference an architecture pattern from Section 2
• [ ] Phase 1 tickets are in the sprint
• [ ] Dependency links exist between blocking tasks
• [ ] No ticket exceeds 2h estimate (decomposed into sub-tasks)
• [ ] Failure mode cross-references are linked
• [ ] Tickets preserve reference implementations, reuse rules, and debt-boundary notes from the brief
• [ ] Configured local MCP provider exposes the required logical capability bindings.
• [ ] Epic links to the configured documentation parent page

Framework Hardening Addendum

• Contract versioning: Ticket input/output contracts include contract_version and compatibility checks.
• Schema validation: Validate incoming task payloads against docs/schemas/build-brief.schema.json before creating any issue.
• Provider resolution: Fail fast if the configured local MCP provider is missing required logical capabilities.
• Idempotency: Every issue create/update operation must include an idempotency key per docs/specs/idempotency-keys.md; retries must not create duplicates.
• Permission logging: Emit structured approval and denial records for every create, update, or close mutation.
• Structured errors: Return field-level validation, provider capability gaps, and upstream dependency failures in a typed error payload.