technical-story

Files (1)

• SKILL.md

SKILL.md (first lines)

# Technical Story Skill

Draft polished, Jira-ready Technical Stories with Acceptance Criteria, for backlog
items that describe system or engineering concerns rather than a human user experience.

This skill complements the `user-story` skill. A User Story centres on a human persona
and the value they get; a Technical Story centres on the **system or platform** and the
technical outcome (reliability, security, consistency, observability, testability). The
consumer of the capability is the platform itself, so the story statement names the
system, not a human role.

---

## Step 1 — Confirm This Is a Technical Story

Use this skill when the PBI describes an engineering concern with no direct human actor.
If the item describes a human-facing feature, UI, or classic experience, use the
`user-story` skill instead.

| Signal in the request | Story type |
|---|---|
| IaC resource provisioning (Cloud Run, GCS, Pub/Sub, LB) | **Technical** |
| IAM / service account / Workload Identity configuration | **Technical** |
| GitHub Actions / CI-CD / OpenTofu apply / deploy workflow | **Technical** |
| Artifact Registry publish, prune, or versioning | **Technical** |
| Backend handler, function logic, message processing | **Technical** |
| API endpoint a human directly calls in a journey | User Story |
| Dashboard, screen, form, or UI feature | User Story |
| Auth flow described from the user's perspective | User Story |

If genuinely mixed (e.g. "let users export a report" where the export job is the work),
split it: a User Story for the experience and a Technical Story for the enabling job,
linked as dependencies.

---

## Step 2 — Choose the Sub-Type

Every Technical Story is one of two sub-types. Pick based on the primary concern:

- **Infrastructure** — provisioning, configuration, access, pipelines. The deliverable
  is a resource, binding, or workflow that exists and behaves correctly. Owners are
  typically platform/infra engineers. Definition of Done is verified in the cloud
  console, the IaC plan, or the pipeline run.
- **Application** — logic that runs *on* the infrastructure. The deliverable is correct
  behaviour: inputs handled, outputs produced, failures managed, logs emitted. Owners
  are typically application engineers. Definition of Done is verified by tests and
  observed runtime behaviour.

A single capability often needs **both**: one Infrastructure story to provision the
Cloud Run service, one Application story for its handler logic. When that is the case,
produce both and link them — the Infrastructure story typically blocks the Application
story's integration testing.

---

## Output Format

Use this exact structure. It mirrors the `user-story` skill's format so the two sit
side by side, with two differences: the `Type` line names the sub-type, and the story
statement names the **system/platform**, not a persona.

```
**Title:** [Short, imperative-phrased summary — max 10 words]

**Type:** Technical Story — [Infrastructure / Application]
**Priority:** [Critical / High / Medium / Low]
**Story Points:** [1 / 2 / 3 / 5 / 8 / 13 — Fibonacci scale]

---

**Technical Story**

As the [platform / service / system name],
I need [capability or resource],
So that [technical outcome — reliability, security, consistency, observability].

---

**Acceptance Criteria**

---

**AC1 - [Criterion Name]**

Given [system state or precondition],
When [action, trigger, or event],
Then [observable, verifiable outcome].

---

**AC2 - [Criterion Name]**

Given [system state or precondition],
When [action, trigger, or event],
Then [observable, verifiable outcome].

---

[Add as many AC[N] - Name blocks as needed — minimum 3, maximum 8]

---

**Out of Scope**
- [What resource, logic, concern, or environment is explicitly excluded]

**Dependencies**
- [Prerequisite APIs, modules, service accounts, linked stories — or "None"]

**Notes**
[Naming conventions, error-handling decisions, open questions, per-environment split.]
```

---

## Writing Guidelines

### Title
- Imperative verb ("Provision", "Implement", "Configure", "Publish", "Enable").

From craigspaterson/agent-skills, MIT.

More from craigspaterson/agent-skills