use-case

Version: 1.0.0 | Framework: Jerry Framework | Constitutional compliance: P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception) Status: PROPOSED | Author: eng-backend | Date: 2026-03-09

---

Document Sections

Section	Purpose
Document Audience	Who reads which sections
Purpose	What this skill does and key capabilities
When to Use	Activation conditions and anti-patterns
Available Agents	Agent routing table with decision signals
P-003 Agent Topology	ASCII hierarchy diagram -- multi-agent topology
Invoking an Agent	Three invocation modes
Methodology Reference	Cockburn 12-step and Jacobson UC 2.0 summary
Input Requirements	Prerequisites per agent
Output Artifacts	Use case artifact and slice formats
Integration Points	Cross-skill connections
Routing Entry (Priority 13)	Trigger map entry for mandatory-skill-usage.md
Constitutional Compliance	Principle-to-agent mapping
Quick Reference	Common workflows and agent selection
Elaboration State Matrix	2D valid-state and readiness matrix
References	File paths and external citations

---

Document Audience

Level	Audience	Sections
L0	Stakeholders, project managers	Purpose, When to Use, Quick Reference
L1	Developers, analysts using the skill	Available Agents, Invoking an Agent, Methodology Reference, Input Requirements, Output Artifacts
L2	Framework maintainers, reviewers	P-003 Agent Topology, Integration Points, Constitutional Compliance, References

---

Purpose

The /use-case skill provides guided use case authoring and decomposition through two complementary agents that implement industry-standard methodologies:

1. uc-author implements Cockburn's 12-step writing process and Jacobson UC 2.0 progressive narrative levels (Briefly Described through Fully Described) for creating structured use case artifacts.
2. uc-slicer implements Jacobson UC 2.0 Activities 2, 4, and 5 for decomposing use cases into implementation-ready slices with INVEST criteria verification, and producing the realization interaction sequences that enable downstream /test-spec and /contract-design consumption.

Key Capabilities:

• Progressive elaboration: artifacts evolve through four detail levels (BRIEFLY_DESCRIBED, BULLETED_OUTLINE, ESSENTIAL_OUTLINE, FULLY_DESCRIBED) with explicit prerequisites at each level transition
• Breadth-first authoring (PAT-001): Steps 1-4 for all use cases before depth elaboration of any single use case, preventing missed actors and incorrect goal levels
• Cockburn goal-level classification: SUMMARY (+), USER_GOAL (!), SUBFUNCTION (-) using the sea-metaphor (Cloud/Kite/Sea Level/Fish/Clam)
• Schema-validated output: all artifacts validate against docs/schemas/use-case-realization-v1.schema.json
• Five-state slice lifecycle: SCOPED > PREPARED > ANALYZED > IMPLEMENTED > VERIFIED with worktracker Story entity integration
• INVEST criteria verification on every slice before state advancement
• Realization interaction sequences ($.interactions[]) that feed directly into /contract-design cd-generator and /test-spec tspec-generator

---

When to Use

Activate this skill when:

• Writing a new use case from a stakeholder description or actor goal
• Elaborating an existing use case artifact to a higher detail level (e.g., BULLETED_OUTLINE to ESSENTIAL_OUTLINE)
• Decomposing a use case into implementation-ready slices (Jacobson UC 2.0 Activity 2)
• Preparing slices with test cases and enhanced narrative (Activity 4)
• Analyzing slices to produce realization interaction sequences (Activity 5)
• Identifying actors, goals, and system scope for a new system or feature

NEVER invoke this skill when:

• Task is generating BDD test specifications from use case artifacts -- Consequence: /use-case creates use case artifacts; /test-spec consumes them to produce Gherkin Feature files. Using /use-case for test generation produces use case artifacts, not test specifications.
• Task is generating API contracts from use case artifacts -- Consequence: /use-case produces structured use case artifacts with interaction sequences; /contract-design transforms those interactions into OpenAPI specifications.
• Task is adversarial quality review of deliverables -- Consequence: use /adversary for quality scoring and adversarial critique.
• Task is requirements engineering with NASA NPR 7123.1D compliance -- Consequence: /use-case implements Cockburn/Jacobson methodology, not NPR requirements processes; use /nasa-se instead.
• Task is researching or analyzing a problem -- Consequence: /use-case is an authoring tool, not a research or analysis methodology; use /problem-solving instead.

---

Available Agents

Agent	Role	Model	Cognitive Mode	Tool Tier	Output Location	Decision Signal
uc-author	Creates and elaborates use case artifacts using Cockburn's 12-step writing process and Jacobson UC 2.0 progressive narrative levels	sonnet	integrative	T2	projects/${JERRY_PROJECT}/use-cases/UC-{DOMAIN}-{NNN}-{slug}.md	"write", "create", "author", "elaborate", "expand", "describe", "draft", "refine", "use case"
uc-slicer	Decomposes use cases into implementation-ready slices following Jacobson UC 2.0 Activities 2, 4, and 5	sonnet	systematic	T2	Same artifact as input (in-place update adding $.slices[], $.interactions[])	"slice", "decompose", "break down", "prepare", "analyze", "realize", "INVEST", "interaction sequence"

Default routing: When intent is ambiguous between authoring and slicing, route to uc-author first. Authoring must precede slicing -- uc-slicer requires detail_level >= ESSENTIAL_OUTLINE which is produced by uc-author. When the user says "create a use case and slice it," invoke uc-author first, then uc-slicer on the output.

---

P-003 Agent Topology

Both uc-author and uc-slicer are T2 worker agents. They are invoked independently from MAIN CONTEXT. They do NOT invoke each other. The output of uc-author (use case artifact on disk) is consumed by uc-slicer via the filesystem -- not via direct agent-to-agent communication.

MAIN CONTEXT (orchestrator)
    |
    +-- uc-author (T2 worker) -- via Task tool
    |   Reads: Project context, existing UC artifacts
    |          docs/schemas/use-case-realization-v1.schema.json
    |          skills/use-case/rules/use-case-writing-rules.md
    |          skills/use-case/templates/*.template.md
    |   Writes: UC artifact (.md with YAML frontmatter)
    |
    +-- uc-slicer (T2 worker) -- via Task tool
        Reads: UC artifact (.md) -- produced by uc-author
               docs/schemas/use-case-realization-v1.schema.json
               skills/use-case/rules/use-case-writing-rules.md
        Writes: Updated UC artifact (adds $.slices[], $.interactions[])
                Optional: separate slice documents

Workers do NOT invoke each other.
uc-author output (UC artifact) is consumed by uc-slicer via filesystem.
Cross-agent data flow is mediated by shared artifact files on disk (P-003 compliant).

---

Invoking an Agent

Natural Language Invocation

Write a use case for user authentication in the AUTH domain.

Elaborate UC-AUTH-001 to Essential Outline level.

Slice UC-AUTH-001 into implementation-ready increments.

Explicit Agent Invocation

Use uc-author to create a use case for user credential validation
at USER_GOAL level in the AUTH domain.

Use uc-slicer to decompose UC-AUTH-001 from
projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
into slices with INVEST verification.

Task Tool Invocation (composition file)

# Invoke uc-author via Task tool
task:
  agent: skills/use-case/composition/uc-author.agent.yaml
  prompt: |
    Create a use case for user credential validation in the AUTH domain.
    Goal level: USER_GOAL. Target detail level: ESSENTIAL_OUTLINE.
    Output path: projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md

# Invoke uc-slicer via Task tool
task:
  agent: skills/use-case/composition/uc-slicer.agent.yaml
  prompt: |
    Slice the use case at:
    projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
    Perform Activities 2, 4, and 5. Create worktracker Story entities.

---

Methodology Reference

Cockburn 12-Step Writing Process (uc-author)

Full rules are in skills/use-case/rules/use-case-writing-rules.md. Steps are loaded progressively per target detail level.

Step	Action	Output Added	Detail Level Gate
1	Identify goal level (SUMMARY/USER_GOAL/SUBFUNCTION)	goal_level, goal_symbol	BRIEFLY_DESCRIBED
2	Identify scope and domain	scope, domain, id	BRIEFLY_DESCRIBED
3	Identify primary actor and supporting actors	primary_actor, supporting_actors[], stakeholders[]	BRIEFLY_DESCRIBED
4	Write the brief (title + 3-step basic_flow minimum)	title, basic_flow (3 steps)	BRIEFLY_DESCRIBED
5	Write the full basic flow (3-9 steps, typed)	basic_flow (3-9 steps, all with type field)	BULLETED_OUTLINE
6	Write preconditions, postconditions, trigger	preconditions[], postconditions, trigger	BULLETED_OUTLINE
7	Write extensions (exception handling flows)	extensions[]	ESSENTIAL_OUTLINE
8	Write alternative flows	alternative_flows[]	ESSENTIAL_OUTLINE
9	Verify Cockburn's six quality indicators	Pass all 6	ESSENTIAL_OUTLINE
10	Advance to ESSENTIAL_OUTLINE	detail_level: ESSENTIAL_OUTLINE	ESSENTIAL_OUTLINE
11	Extract sub-use cases	related_use_cases[]	FULLY_DESCRIBED
12	Advance to FULLY_DESCRIBED	detail_level: FULLY_DESCRIBED	FULLY_DESCRIBED

Jacobson UC 2.0 Slice Lifecycle (uc-slicer)

Activity	Steps	Output
Activity 2: Slice the Use Cases	Identify slice candidates, apply INVEST, create slice definitions	$.slices[] with slice_state: SCOPED
Activity 4: Prepare a Slice	Define test cases, enhance narrative, create worktracker Story	slice_state: PREPARED
Activity 5: Analyze a Slice	Identify system elements, allocate responsibilities, produce interactions	$.interactions[], realization_level: INTERACTION_DEFINED, slice_state: ANALYZED

Goal Level Classification (Cockburn Sea Metaphor)

Level	Symbol	Description	Example
SUMMARY	(+)	Cloud/Kite -- high-level business goals	"Manage inventory"
USER_GOAL	(!)	Sea Level -- what an actor wants to achieve in one sitting	"Check out a book"
SUBFUNCTION	(-)	Fish/Clam -- substeps within a user goal	"Validate credentials"

---

Input Requirements

uc-author Input

Requirement	Constraint
User request describes a system capability or actor goal	Free text; agent applies H-31 if ambiguous
OR: existing use case artifact path for elaboration	File must exist, $.work_type = USE_CASE

uc-slicer Input

Requirement	Constraint	Consequence of Violation
Artifact exists at specified path	File must be readable	REJECT with path error
$.work_type = USE_CASE	Discriminator field	REJECT
$.detail_level >= ESSENTIAL_OUTLINE	Must not be BRIEFLY_DESCRIBED or BULLETED_OUTLINE	REJECT with actionable message: "Use uc-author to elaborate first"
$.basic_flow has 3-9 steps	basic_flow array	REJECT
$.extensions non-empty	At least 1 extension	REJECT

---

Output Artifacts

uc-author: Use Case Artifact

Path: projects/${JERRY_PROJECT}/use-cases/UC-{DOMAIN}-{NNN}-{slug}.md Format: YAML frontmatter + Markdown narrative body Schema: docs/schemas/use-case-realization-v1.schema.json Templates: skills/use-case/templates/use-case-{brief|casual|realization}.template.md

uc-slicer: Updated Use Case Artifact (in-place)

Path: Same as input artifact (in-place update) Added fields: $.slices[], $.interactions[], $.slice_ids[], $.slice_state, $.realization_level Optional: Separate slice documents at projects/${JERRY_PROJECT}/use-cases/UC-{DOMAIN}-{NNN}/slices/

Downstream Consumption Readiness

Consumer Skill	Minimum Input Level	Key Field Required
/test-spec (tspec-generator)	detail_level >= ESSENTIAL_OUTLINE	$.basic_flow[*].type, $.extensions[]
/contract-design (cd-generator)	realization_level = INTERACTION_DEFINED	$.interactions[]

---

Integration Points

Integration	Direction	Mechanism	Pre-Condition
/use-case to /test-spec	tspec-generator reads UC artifact produced by uc-author	Shared artifact file validated against schema	$.detail_level >= ESSENTIAL_OUTLINE, $.extensions non-empty, $.basic_flow[*].type present
/use-case to /contract-design	cd-generator reads UC artifact after uc-slicer Activity 5	Shared artifact file validated against schema	$.realization_level = INTERACTION_DEFINED, $.interactions non-empty
/use-case to /worktracker	uc-slicer creates Story entities for PREPARED slices	uv run jerry items create via Bash (H-05 compliant; P-003 no Task delegation)	Slices at slice_state >= PREPARED
All three skills share the same UC artifact	Shared schema: docs/schemas/use-case-realization-v1.schema.json	Schema validates input at every consumer boundary	Valid YAML frontmatter with $.work_type = USE_CASE

---

Routing Entry (Priority 13)

Per agent-routing-standards.md enhanced 5-column trigger map format. Priority 13 places /use-case above /test-spec (14) and /contract-design (15), reflecting that use case authoring precedes both test specification and contract generation in the pipeline.

Detected Keywords	Negative Keywords	Priority	Compound Triggers	Skill
use case, use-case, write use case, create use case, author use case, elaborate use case, Cockburn, UC 2.0, Jacobson, actor goal, basic flow, main success scenario, extensions, alternative flow, use case slice, slice use case, INVEST criteria, use case realization, interaction sequence, goal level, primary actor, fully dressed, essential outline	BDD, Gherkin, feature file, test spec, test specification, OpenAPI, API contract, API spec, generate contract, adversarial, tournament, transcript, penetration, exploit, code review, documentation, tutorial, requirements specification, V&V, technical review	13	"write use case" OR "create use case" OR "use case" OR "author use case" OR "elaborate use case" OR "slice use case" OR "use case realization" (phrase match)	/use-case

Disambiguation notes:

• "use case" routes here. "use case to test" routes to /test-spec via that skill's compound triggers.
• "use case to API" routes to /contract-design via that skill's compound triggers.
• "actor" alone is excluded (ambiguous with general discussion). "actor goal" or "primary actor" route here.
• "INVEST" alone is excluded (ambiguous with financial context in /pm-pmm). "INVEST criteria" routes here via compound trigger proximity.

---

Constitutional Compliance

Principle	Agent	Application
P-001 (Truth/Accuracy)	uc-author	Every flow step is grounded in stakeholder input or domain knowledge. No invented actors or goals.
P-001 (Truth/Accuracy)	uc-slicer	INVEST assessments report actual criteria pass/fail. Coverage metrics are verifiable.
P-002 (File Persistence)	Both	All outputs persisted to files at projects/${JERRY_PROJECT}/use-cases/.
P-003 (No Recursive Subagents)	Both	Both are T2 worker agents. Neither has Task tool access. Neither invokes the other directly.
P-004 (Provenance)	Both	YAML frontmatter carries author, version, created_at, updated_at for full audit trail.
P-020 (User Authority)	uc-author	Does not override user decisions about scope, actor list, goal level, or target detail level.
P-020 (User Authority)	uc-slicer	Does not override user decisions about slice boundaries, priority ordering, or lifecycle state transitions.
P-022 (No Deception)	uc-author	Reports actual detail level achieved; does not claim ESSENTIAL_OUTLINE when extensions are missing.
P-022 (No Deception)	uc-slicer	Reports actual INVEST pass/fail per slice; does not advance state when prerequisites are not met.

---

Quick Reference

Common Workflows

Workflow	Agent Sequence	Typical Duration
Create brief use case	uc-author (BRIEFLY_DESCRIBED)	1-2 minutes
Create working use case	uc-author (BULLETED_OUTLINE -- default)	2-3 minutes
Create test-ready use case	uc-author (ESSENTIAL_OUTLINE)	3-5 minutes
Elaborate existing UC to higher level	uc-author (reads existing, elaborates)	2-4 minutes
Slice use case into increments	uc-slicer (Activities 2+4)	2-4 minutes
Analyze slices for interaction sequences	uc-slicer (Activity 5) -- prerequisite for /contract-design	2-3 minutes
Full realization pipeline	uc-author (ESSENTIAL_OUTLINE) -> uc-slicer (Activities 2+4+5)	5-10 minutes
End-to-end: UC to test specs and contracts	uc-author -> uc-slicer -> tspec-generator + cd-generator	10-20 minutes

Agent Selection Hints

Signal	Route to
"Write", "create", "author", "draft", "elaborate", "expand"	uc-author
"Slice", "decompose", "break down", "INVEST", "realize"	uc-slicer
Ambiguous intent	uc-author first (authoring must precede slicing)
"Create and slice"	uc-author, then uc-slicer on output
"Generate tests from use case"	Not this skill -- route to /test-spec
"Generate API contract from use case"	Not this skill -- route to /contract-design

Detail Level Quick Check

Level	Minimum Content	Ready For
BRIEFLY_DESCRIBED	Title + 3-step basic flow + goal level	Human review only
BULLETED_OUTLINE	Steps 1-6 complete (actors, typed flow, pre/postconditions)	Internal discussion
ESSENTIAL_OUTLINE	Steps 1-10 complete (extensions, alternative flows, quality indicators)	/test-spec, /use-case uc-slicer, and /contract-design (after uc-slicer Activity 5 adds interactions)
FULLY_DESCRIBED	Steps 1-12 complete (sub-use cases extracted, all exceptions)	All consumers (maximum completeness)

Note: ESSENTIAL_OUTLINE + uc-slicer Activity 5 (realization_level = INTERACTION_DEFINED) is the minimum prerequisite for /contract-design. FULLY_DESCRIBED is not required. See Downstream Consumption Readiness table above.

---

Elaboration State Matrix (detail_level x realization_level)

This 2D matrix shows which (detail_level, realization_level) combinations are valid and which transitions produce downstream-consumable artifacts.

	OUTLINED	STORY_DEFINED	INTERACTION_DEFINED
BRIEFLY_DESCRIBED	Valid (initial state)	NOT PERMITTED (schema allOf block)	NOT PERMITTED (schema allOf block)
BULLETED_OUTLINE	Valid (working spec)	Valid (slices created, no interactions yet)	NOT PERMITTED (schema allOf block)
ESSENTIAL_OUTLINE	Valid (pre-slice)	Valid (Activities 2+4 complete)	Ready for /contract-design and /test-spec
FULLY_DESCRIBED	Valid (pre-slice)	Valid (Activities 2+4 complete)	Ready for /contract-design and /test-spec (maximum completeness)

Key rules:

• INTERACTION_DEFINED requires detail_level >= ESSENTIAL_OUTLINE -- enforced by the schema's allOf conditional constraint
• STORY_DEFINED requires detail_level >= BULLETED_OUTLINE (slices need typed flow steps)
• /contract-design requires realization_level = INTERACTION_DEFINED (independent of detail_level)
• /test-spec requires detail_level >= ESSENTIAL_OUTLINE (independent of realization_level)
• The most common production target is (ESSENTIAL_OUTLINE, INTERACTION_DEFINED)

---

References

File	Purpose
skills/use-case/agents/uc-author.md	uc-author agent definition
skills/use-case/agents/uc-author.governance.yaml	uc-author governance metadata
skills/use-case/agents/uc-slicer.md	uc-slicer agent definition
skills/use-case/agents/uc-slicer.governance.yaml	uc-slicer governance metadata
skills/use-case/composition/uc-author.agent.yaml	uc-author canonical agent YAML (Task invocation)
skills/use-case/composition/uc-author.prompt.md	uc-author system prompt copy
skills/use-case/composition/uc-slicer.agent.yaml	uc-slicer canonical agent YAML (Task invocation)
skills/use-case/composition/uc-slicer.prompt.md	uc-slicer system prompt copy
skills/use-case/rules/use-case-writing-rules.md	Cockburn 12-step + Jacobson UC 2.0 imperative rules
skills/use-case/templates/use-case-brief.template.md	BRIEFLY_DESCRIBED output template
skills/use-case/templates/use-case-casual.template.md	BULLETED_OUTLINE output template
skills/use-case/templates/use-case-realization.template.md	ESSENTIAL_OUTLINE / FULLY_DESCRIBED output template
skills/use-case/templates/use-case-slice.template.md	Separate slice document template (optional)
skills/use-case/tests/BEHAVIOR_TESTS.md	BDD behavior test scenarios for the skill
skills/use-case/samples/sample-use-case.md	Sample use case artifact demonstrating output format
docs/schemas/use-case-realization-v1.schema.json	JSON Schema for use case artifact YAML frontmatter
Cockburn, A. (2001)	Writing Effective Use Cases. Addison-Wesley.
Jacobson, I. et al. (2011)	Use-Case 2.0: The Guide to Succeeding with Use Cases. Ivar Jacobson International.
projects/PROJ-021-use-case/orchestration/use-case-skills-20260308-001/implementation/step-9-use-case-architecture.md	Architecture SSOT

---

Skill Version: 1.0.0 | Framework: Jerry Framework | Constitutional compliance: P-003, P-020, P-022 Author: eng-backend | Date: 2026-03-09 | Status: ACTIVE SSOT: projects/PROJ-021-use-case/orchestration/use-case-skills-20260308-001/implementation/step-9-use-case-architecture.md