Claude-Skills job-stories

Jobs-to-Be-Done story writing that focuses on user situations and motivations rather than personas.

install
source · Clone the upstream repo
git clone https://github.com/borghei/Claude-Skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/borghei/Claude-Skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/project-management/execution/job-stories" ~/.claude/skills/borghei-claude-skills-job-stories && rm -rf "$T"
manifest: project-management/execution/job-stories/SKILL.md
source content

Job Stories Expert

Overview

Write job stories using the Jobs-to-Be-Done (JTBD) framework. Unlike traditional user stories that focus on roles ("As a user..."), job stories focus on the situation, motivation, and desired outcome. This shift produces requirements that are more grounded in real user context and less likely to encode assumptions about who the user is.

When to Use

  • Feature definition -- When you need to articulate what to build and why, grounded in user context.
  • Backlog creation -- When populating a backlog with work items that stay focused on user outcomes.
  • Requirement workshops -- When collaborating with stakeholders to define what "done" looks like.
  • Design briefs -- When giving designers context about the situation and motivation behind a feature.

When NOT to Use

  • When you need strategic backlog items with business context -- use
    wwas/
    instead.
  • When you need lightweight stories for a team already fluent in user story format.
  • When the work is purely technical with no direct user-facing situation.

JTBD Discovery Canvas

Before writing job stories, run a Jobs-to-Be-Done discovery canvas to understand what customers are trying to achieve, where they struggle, and what outcomes they value most. This canvas produces the situational context that feeds directly into job story writing.

When to Run Discovery First

  • Starting a new product area with no existing user research.
  • Entering a new market segment or persona.
  • Backlog items feel disconnected from real user needs.
  • Team debates "what to build" without grounding in customer jobs.

Discovery Canvas Template

1. Customer Jobs

Functional Jobs:

  • [Tasks customers need to perform — keep each bullet 4-8 words]

Social Jobs:

  • [Ways customers want to be perceived socially]

Emotional Jobs:

  • [Emotional states customers seek to achieve or avoid]

2. Pains

Challenges:

  • [Obstacles customers face when performing their jobs]

Costliness:

  • [What customers find too costly in time, money, or effort]

Common Mistakes:

  • [Frequent errors customers make that could be prevented]

Unresolved Problems:

  • [Problems not solved by current solutions]

3. Gains

Expectations:

  • [Ways current solutions fail to meet expectations]

Savings:

  • [Ways savings in time, money, or effort would delight customers]

Adoption Factors:

  • [Factors that would increase the likelihood of adoption]

Life Improvement:

  • [Ways a solution could make customers' lives easier or more enjoyable]

4. Assumptions to Validate

  • [Assumption 1]
  • [Assumption 2]
  • [Assumption 3]

From Canvas to Job Stories

Each row in the discovery canvas maps to job story components:

Canvas SectionMaps ToExample
Customer Jobs (Functional)Motivation (I want to...)"I want to reconcile my accounts"
Pains (Challenges)Situation (When...)"When I discover a discrepancy during month-end close"
Gains (Expectations)Outcome (So I can...)"So I can submit accurate reports before the deadline"

Process:

  1. Run the discovery canvas with stakeholders or from research data.
  2. Identify the highest-impact job-pain-gain clusters.
  3. Write one job story per cluster using the When/Want/So format below.
  4. Validate assumptions before committing to build.

Next Steps After Discovery

  1. Generate prioritized opportunity statements from the canvas (Recommended)
  2. Convert the canvas into a value proposition draft
  3. Generate interview questions to validate top assumptions
  4. Generate a hypothesis backlog for rapid experiments

The Job Story Format

When [situation], I want to [motivation], so I can [outcome].
ComponentFocusQuestion It Answers
When [situation]The context or triggerWhat is happening when the user needs this?
I want to [motivation]The action or capability desiredWhat does the user want to do in this moment?
So I can [outcome]The expected result or benefitWhat does success look like for the user?

Key Principle: Focus on the Job, Not the Role

User stories say "As a [role]..." which anchors the requirement to a persona. Job stories remove the role and instead describe the situation -- the real-world context that creates the need. This matters because:

  • The same person may have different needs in different situations.
  • Different people in the same situation often have the same need.
  • Situations are observable and testable; roles are abstract labels.

Example comparison:

User StoryJob Story
As a budget manager, I want to see a spending report so I can track expenses.When I am preparing my weekly budget, I want to see spending so far this period, so I can adjust before overspending.
As an admin, I want to export user data so I can comply with data requests.When I receive a data subject access request, I want to export all data associated with that person, so I can respond within the 30-day legal deadline.

The job story version is more specific, more testable, and provides better design guidance.

Writing Good Job Stories

Situations (When...)

Good situations are:

  • Specific and observable -- You could watch someone be in this situation.
  • Contextual -- They describe what is happening, not who the person is.
  • Triggering -- They explain what creates the need right now.
Weak SituationStrong Situation
When I use the appWhen I open the app for the first time after signing up
When I need dataWhen I am in a client meeting and need to reference last quarter's results
When I manage my teamWhen a team member submits a time-off request that overlaps with a project deadline

Motivations (I want to...)

Good motivations are:

  • Action-oriented -- They describe doing something, not having something.
  • Solution-agnostic -- They describe the capability, not the implementation.
  • Singular -- One motivation per story.
Weak MotivationStrong Motivation
I want a dashboardI want to see my team's progress at a glance
I want better notificationsI want to be alerted only when something requires my action
I want to manage users and permissionsI want to grant a new team member access to the project (split into two if needed)

Outcomes (So I can...)

Good outcomes are:

  • Benefit-focused -- They describe the end result, not the means.
  • Measurable or observable -- You can tell if the outcome was achieved.
  • Meaningful -- They connect to something the user genuinely cares about.
Weak OutcomeStrong Outcome
So I can use the featureSo I can complete my weekly report in under 10 minutes
So I can be productiveSo I can identify which tasks are blocked before standup
So I can do my jobSo I can respond to the customer within our 4-hour SLA

INVEST Quality Criteria

Apply INVEST to every job story before it enters the backlog:

CriterionQuestionRed Flag
IndependentCan this story be delivered without depending on another story?"This only works after story X is done"
NegotiableIs the implementation open to discussion, or is it prescribing a solution?Motivation says "I want a dropdown menu" instead of "I want to select from available options"
ValuableDoes the outcome deliver clear value to the user?Outcome is vague ("so I can use it") or internal ("so the database is normalized")
EstimableCan the team estimate the effort?Situation is too vague to understand scope
SmallCan this be completed in one sprint?Story covers multiple distinct situations or motivations
TestableCan you write acceptance criteria that verify the outcome?Outcome is subjective ("so I feel confident")

Story Template

For each job story, produce a card with the following structure:

### [Title]

**Job Story:**
When [situation], I want to [motivation], so I can [outcome].

**Design:** [Link to design file or "TBD"]

**Acceptance Criteria:**

1. [ ] [Observable outcome that verifies the story is complete]
2. [ ] [Observable outcome]
3. [ ] [Observable outcome]
4. [ ] [Observable outcome]
5. [ ] [Observable outcome]
6. [ ] [Observable outcome]

Acceptance Criteria Guidelines

  • Write 6-8 acceptance criteria per story.
  • Focus on outcomes, not implementation steps.
  • Each criterion should be independently verifiable.
  • Use the pattern: "[Thing] [does/shows/enables] [expected behavior] [under condition]."
  • Include edge cases and error states, not just the happy path.

Good acceptance criteria examples:

  1. The spending summary shows all transactions from the current period, grouped by category.
  2. Transactions from previous periods are excluded from the current period total.
  3. The summary updates within 5 seconds of a new transaction being recorded.
  4. If no transactions exist for the current period, a message explains that no spending has been recorded yet.
  5. The summary is accessible on mobile screens without horizontal scrolling.
  6. Category totals match the individual transaction amounts (no rounding discrepancies).

Bad acceptance criteria examples (avoid):

  • The API returns a 200 status code (implementation detail)
  • The React component renders correctly (implementation detail)
  • It works (not testable)
  • The user is happy (not observable)

Worked Example

Context: A budgeting application for personal finance.

Weekly Budget Check

Job Story: When I am preparing my weekly budget on Sunday evening, I want to see how much I have spent so far this month by category, so I can decide where to cut back before the month ends.

Design: [Link to Figma mock]

Acceptance Criteria:

  1. The spending view shows the current month's transactions grouped by category (e.g., groceries, dining, transport).
  2. Each category displays the total spent and the remaining budget for that category.
  3. Categories that have exceeded their budget are visually distinguished from those within budget.
  4. Tapping a category shows the individual transactions within it.
  5. The view loads within 2 seconds on a standard mobile connection.
  6. If no budget has been set for a category, the category still appears with total spent but no remaining budget indicator.
  7. The date range is fixed to the current calendar month and is clearly displayed.
  8. A "last updated" timestamp shows when transaction data was last synced.

Integration with Other Skills

  • Use
    summarize-meeting/
    to capture the discovery conversations that inform job stories.
  • Use
    wwas/
    when you need to add strategic business context (the "Why") to backlog items.
  • Feed completed job stories into
    ../jira-expert/
    for ticket creation.
  • Use
    brainstorm-okrs/
    to connect job stories back to team objectives.

References

  • See
    references/jtbd-guide.md
    for Jobs-to-Be-Done theory, comparison with user stories, and story splitting techniques.
  • See
    assets/job_story_template.md
    for ready-to-use templates.

Troubleshooting

ProblemLikely CauseResolution
Team writes situations that are too vague ("When I use the app...")Insufficient user research; situations invented at desk rather than observedRequire each situation to reference a specific interview quote, support ticket, or analytics event; use the "could you video this?" test
Motivations prescribe a specific solution ("I want a dropdown...")Team conflates solution with capability; negotiability criterion failingRewrite using "I want to [verb] [object]" pattern without naming UI elements; apply the INVEST-N check before acceptance
Outcomes are not measurable ("So I can be productive")Outcome too abstract; not grounded in observable behaviorAsk "How would you know the user achieved this?" -- if you cannot describe an observable signal, the outcome needs rewriting
Job stories are too large for a single sprintMultiple situations or motivations packed into one storySplit by situation (different contexts become separate stories) or by outcome (different success criteria become separate stories)
Team defaults to user story format despite trainingHabit and muscle memory; Jira templates still use "As a..." formatUpdate Jira issue templates to use JTBD format; run a conversion workshop with 5 real user stories rewritten as job stories
Acceptance criteria describe implementation steps instead of outcomesEngineering team writing criteria from their perspective rather than the user's perspectiveApply the "would the user care about this?" filter; replace API/database criteria with observable behavior statements
Job stories lack connection to strategic objectivesJTBD format focuses on user context but does not inherently include business "why"Pair each job story with a WWAS "Why" statement from
wwas/
; or add an optional "Supports:" field linking to an OKR

Success Criteria

  • 100% of job stories in the backlog follow the "When / I want to / So I can" format correctly
  • All situations reference observable, specific contexts (pass the "could you video this?" test)
  • All motivations are solution-agnostic (no UI element names or implementation details)
  • Each story has 6-8 acceptance criteria focused on observable outcomes, not implementation
  • Every job story passes all 6 INVEST criteria before entering a sprint
  • Defect rate on stories written in JTBD format is 20%+ lower than stories written in traditional format (measured over 3 months)
  • Team members can articulate the difference between a job story and a user story and choose the appropriate format for the context

Scope & Limitations

In Scope: Writing job stories using JTBD "When/Want/So" format, applying INVEST quality criteria, writing outcome-focused acceptance criteria, converting existing user stories to job stories, facilitating story-writing workshops, integrating job stories with Jira backlog items.

Out of Scope: Strategic backlog items with business context (hand off to

wwas/
), product ideation and opportunity discovery (hand off to
discovery/brainstorm-ideas/
), detailed technical specifications, UX research and user interviewing methodology.

Limitations: Job stories work best when the team has access to real user research (interviews, observation, support data). Without user context, teams will invent situations that may not reflect reality. The format is less natural for purely technical or infrastructure work where there is no direct user situation. Job stories and user stories are complementary -- some teams use both formats for different types of work.

Integration Points

IntegrationDirectionWhat Flows
wwas/
ComplementaryWWAS adds strategic "Why" context; job stories add situational "When" context. Use both when needed
summarize-meeting/
Meetings -> StoriesDiscovery conversations and refinement sessions produce the situations that inform job stories
../jira-expert/
Stories -> JiraCompleted job stories become Jira tickets with structured descriptions
discovery/brainstorm-ideas/
Ideas -> StoriesValidated product ideas decompose into job stories for the backlog
execution/brainstorm-okrs/
OKRs -> StoriesTeam objectives define the outcomes that job stories should connect to
execution/prioritization-frameworks/
Stories -> PrioritizationJob stories scored via RICE or other frameworks for sprint planning