uc-engraver

name

uc-engraver

description

Create and update structured Use Case child documents for a parent Design Review / Software Requirements Specification (DR/SRS). Use whenever a user asks to define, write, refine, synchronize, or publish a Use Case, UC, scenario, acceptance checks, or detailed behavior from a PRD, DR/SRS, JTBD, Service Blueprint, Figma, RFC, contract, or task intake. Preserve stable UC/AC IDs, reuse actor names exactly from the linked PRD, expose gaps without inventing behavior, update and verify the parent DR/SRS catalog, and hand confirmed Confluence publication to confluence-librarian.

UC Engraver

Forge the detailed Use Case child document that makes one behavior implementable, testable, and traceable without duplicating the parent DR/SRS.

When to use this skill

Use this skill to:

• create one or more Use Cases from a parent DR/SRS, linked PRD, JTBD, Service Blueprint, Figma flow, RFC, contract, or task intake;
• update an existing Use Case after a confirmed behavior, contract, tracking, compliance, or acceptance change;
• add a Use Case while dr-blacksmith is authoring or updating a parent DR/SRS;
• synchronize a Use Case's local child document and its parent DR/SRS catalog.

Do not use it to create a new parent DR/SRS. If the parent document cannot be located, ask for its path and stop. Do not embed detailed Use Case bodies in the parent document.

Output contract

Write one Markdown file per selected Use Case at use-cases/uc-XX-<slug>.md, relative to the parent DR/SRS directory, unless the user explicitly requests another path. When the user requests all Use Cases in a parent catalog, create or update every selected catalog entry. Use templates/use-case.md and never overwrite the bundled template.

• Preserve the existing UC-XX ID when updating. Allocate the next non-conflicting ID only for a genuinely new Use Case.
• Preserve existing Use Case-local AC-XX IDs when their meaning remains unchanged. Add a new ID only for new acceptance meaning; do not renumber existing checks.
• Write visible content in English unless another language is requested. Stable IDs, status values, endpoint names, metric identifiers, and URLs are machine-facing and remain unchanged.
• Keep the frontmatter status and the visible design-maturity value unchanged unless the user explicitly requests a lifecycle transition.
• Keep every unknown, contradiction, and unverified claim visible as an assumption, open question, proposed value, or justified N/A.
• A published child Use Case is not complete until the parent Confluence catalog row contains both the local child link and the returned Confluence URL. Treat the parent update and its verification as part of publication, not as optional follow-up work.

Source and actor discipline

1. Read the parent DR/SRS and its linked PRD before writing.
2. Treat the linked PRD actor catalog as authoritative. Copy actor names exactly, including capitalization, punctuation, singular/plural form, and qualifiers. Do not translate, normalize, or substitute an actor name.
3. Reuse the parent DR/SRS UC-XX catalog, linked JTBD IDs, priorities, and known links. Treat conflicts with the PRD, DR/SRS, Service Blueprint, Figma, RFC, or contracts as open questions; do not silently reconcile them.
4. Use accepted RFC decisions only after they have been propagated into the parent DR/SRS.

Required Use Case structure

Complete every section in the bundled template:

• stable ID, status, priority, and parent DR/SRS metadata;
• linked JTBD;
• primary and secondary actors;
• source artifact, including Call for Task when applicable;
• Service Blueprint step and design maturity;
• trigger and preconditions;
• main, alternate, and exception/edge-case flows;
• postconditions;
• numbered binary acceptance checks local to the Use Case;
• tracking events;
• relevant Service Blueprint, Figma, endpoint/contract, validation, and sequence-diagram references.

Keep these body fields in the same order as the DR-01 Use Case template so the Markdown maps predictably to Confluence. A sequence diagram may be inline Mermaid/PlantUML or a link to a repository diagram.

The child document owns behavior-level detail. The parent owns the catalog and cross-Use Case architecture, NFRs, contracts, rollout, validation strategy, readiness, and change propagation.

Workflow

1. Locate the parent. Find the existing parent DR/SRS and read the complete Use Case index. If no parent path is available, ask for it and stop.
2. Collect evidence. Read the linked PRD actor catalog, JTBD, Service Blueprint, Figma, RFC/ADR, APIs/events/data contracts, tracking registry, reviews, tests, and supplied task context. Ask only about contradictions or missing decisions that affect behavior, ownership, contracts, compliance, tracking, or readiness.
3. Select catalog entries. Match a requested UC-XX by ID or unambiguous title. When the user requests all Use Cases, select every applicable parent catalog entry. For a genuinely new Use Case, allocate the next available stable ID without renumbering existing entries.
4. Draft or update each child. Fill the complete template for every selected entry. Reuse PRD actor names exactly, preserve stable IDs, and distinguish confirmed behavior from proposed behavior, assumptions, and open questions.
5. Validate each child. Check that flows are coherent, acceptance checks are binary and traceable, tracking is explicit or justified N/A, a sequence diagram is supplied inline or by link, links and IDs are consistent, and no unsupported decision was invented.
6. Synchronize the parent. Update every selected row in the existing parent DR/SRS Use Case index in the same workflow. Keep each row's ID, title, linked JTBD, priority, child-document link, and status/gap aligned. Preserve the parent's catalog-only boundary.
7. Record propagation. When a Use Case changes confirmed behavior, contracts, tracking, privacy/security, or acceptance checks, update the parent open-question/decision propagation area when the change requires coordination, and identify affected downstream artifacts without editing artifacts owned by another skill.
8. Offer publication. After the local child and parent are valid, ask whether the user wants a Confluence child page. After confirmation, hand the child source, parent page context, title, operation, language, and preservation constraints to confluence-librarian. Do not publish directly. Keep both the local Markdown link and the returned Confluence URL in the parent catalog. When the parent catalog is itself published, ensure the Confluence parent page is updated and re-fetched so it no longer contains TBD or missing-child placeholders. If that synchronization fails, report publication as incomplete rather than claiming success.

Clarification rules

• Ask rather than infer actors, JTBD links, priority, ownership, behavior, targets, contracts, tracking, or approval/lifecycle status.
• Prefer an explicit open question over a plausible flow or acceptance check.
• Use N/A — <confirmed reason> only when the source or user confirms that a section does not apply.
• Do not turn a user story into a Use Case without defining the observable trigger, system behavior, outcomes, and binary acceptance checks.
• Do not duplicate detailed child content in the parent DR/SRS.

Direct and delegated invocation

When invoked directly, own the complete child-authoring and parent-sync workflow. When invoked by dr-blacksmith, return every created or updated child path, stable ID, parent index change, unresolved gap, and Confluence URL so dr-blacksmith can continue the parent document workflow. For published children, also return the verified parent-page URL and the synchronized row state.