reuse-surface/specs/UseCaseCatalog.md

UseCaseCatalog.md — reuse-surface

1. Purpose

This Use Case Catalog captures the primary use cases for reuse-surface, a capability registry and reuse assessment surface.

reuse-surface exists to make capabilities visible, comparable, reusable, and assessable across planning, implementation, operation, and product evolution. A capability that is not represented in the registry is considered invisible for reuse within the scope of this product.

The catalog is designed for human and agentic consumers. It supports product planning, architecture work, implementation selection, capability governance, and evidence-based reuse decisions.

2. Scope

2.1 In Scope

reuse-surface supports the following capability registry functions:

• Register capabilities and their metadata.
• Assess internal maturity through Discovery and Availability.
• Expose external consumer-derived evidence through Completeness and Reliability.
• Support planning reuse based on capability Discovery maturity.
• Support implementation reuse based on capability Availability maturity.
• Help consumers find, compare, select, and reuse capabilities.
• Track INTENT, SCOPE, expectation satisfaction, and expectation breaks.
• Track quality signals such as bugs, support issues, star ratings, operational evidence, and consumer feedback.
• Provide registry information in forms usable by humans, CLIs, automation, and agents.

2.2 Out of Scope

reuse-surface does not itself implement the registered capabilities.

It does not replace:

• Source code repositories.
• Package registries.
• Service catalogs.
• Observability platforms.
• Issue trackers.
• Product management systems.
• Architecture decision records.

Instead, it references, aggregates, and interprets evidence from those sources where useful.

3. Actors

Actor	Description
Product Planner	Uses capabilities to structure product ideas, roadmaps, MVPs, and enhancements.
Architect	Uses the registry to reason about capability boundaries, dependencies, alternatives, and reuse potential.
Implementer	Looks for reusable source modules, CLIs, SDKs, services, or platform capabilities.
Agentic Coding Agent	Uses registry metadata to find relevant capabilities and avoid unnecessary reinvention.
Capability Owner	Maintains capability entries, maturity levels, scope, evidence, and links.
Platform Owner	Manages shared capabilities and decides which capabilities should become platform services.
Product Owner	Assesses whether capability SCOPE satisfies declared INTENT and consumer expectations.
Consumer	Uses a capability through documentation, code, package, CLI, SDK, service, platform interface, or cloud offering.
Reviewer	Checks registry entries for consistency, evidence quality, and maturity claims.
Governance Maintainer	Maintains standards, schemas, scoring rules, and registry quality expectations.

4. Capability Maturity Dimensions

The registry uses four primary dimensions.

Dimension	Type	Purpose
Discovery	Internal maturity	How reusable the capability is for planning, orientation, comparison, roadmap design, and architectural reasoning.
Availability	Internal maturity	How the capability can be consumed by implementation or operational consumers.
Completeness	External evidence	How well current SCOPE satisfies declared INTENT and consumer expectations.
Reliability	External evidence	How consistently the capability satisfies consumer-relevant quality expectations.

Canonical short form:

D5 / A4 / C3 / R3

This means:

• Discovery: Grounded
• Availability: Service API / SDK
• Completeness: Functional Core
• Reliability: Usable

5. Use Case Scoring Dimensions

Each use case may be scored with the following dimensions.

Dimension	Scale	Meaning
Planning Value	0–2	How strongly the use case supports planning reuse.
Implementation Value	0–2	How strongly the use case supports implementation reuse.
Governance Value	0–2	How strongly the use case supports registry quality, ownership, and decision discipline.
MVP Relevance	0–2	Whether the use case should be included early.
Complexity	0–2	Expected effort or conceptual complexity. 0 = low, 2 = high.
Automation Potential	0–2	How suitable the use case is for CLI, API, or agentic automation.

Suggested interpretation:

0 = low / not relevant / not needed yet
1 = useful / medium / later candidate
2 = high / central / early priority

6. Use Case Index

ID	Title	Primary Actor	Planning Value	Implementation Value	MVP Relevance
UC-RS-001	Register a New Capability	Capability Owner	2	1	2
UC-RS-002	Classify Capability Discovery Maturity	Capability Owner	2	0	2
UC-RS-003	Classify Capability Availability	Capability Owner	1	2	2
UC-RS-004	Search for Capabilities by Planning Need	Product Planner	2	0	2
UC-RS-005	Search for Capabilities by Consumption Mode	Implementer	0	2	2
UC-RS-006	Compare Capability Candidates	Architect	2	2	2
UC-RS-007	Identify Reuse Gaps for MVP Planning	Product Planner	2	1	2
UC-RS-008	Track SCOPE vs INTENT Completeness	Product Owner	2	1	1
UC-RS-009	Track Reliability Evidence	Capability Owner	1	2	1
UC-RS-010	Record Broken Consumer Expectations	Consumer	2	1	1
UC-RS-011	Promote a Capability to Higher Discovery Maturity	Capability Owner	2	0	1
UC-RS-012	Promote a Capability to Higher Availability	Implementer	0	2	1
UC-RS-013	Use Registry Metadata in Agentic Coding	Agentic Coding Agent	1	2	2
UC-RS-014	Generate Capability Reuse Recommendations	Architect	2	2	1
UC-RS-015	Detect Duplicate or Overlapping Capabilities	Governance Maintainer	2	1	1
UC-RS-016	Maintain Capability Relations	Architect	2	2	1
UC-RS-017	Review Capability Entry Quality	Reviewer	1	1	1
UC-RS-018	Publish a Human-Readable Capability Catalog	Platform Owner	2	1	1
UC-RS-019	Publish a Machine-Readable Registry Export	Agentic Coding Agent	1	2	2
UC-RS-020	Select Capabilities for Platformization	Platform Owner	2	2	1
UC-RS-021	Identify Capabilities Ready for Commercial Offering	Product Owner	2	2	0
UC-RS-022	Track Capability Evolution Over Time	Capability Owner	2	1	1
UC-RS-023	Validate Registry Entries Against Schema	Governance Maintainer	1	2	2
UC-RS-024	Produce Capability Maturity Reports	Governance Maintainer	2	1	1

7. Use Cases

UC-RS-001 — Register a New Capability

Primary Actor: Capability Owner
Supporting Actors: Architect, Reviewer, Agentic Coding Agent

Intent

Create a new visible capability entry in the registry so the capability can be considered for reuse.

Trigger

A person or agent identifies a capability candidate that should be made visible for planning or implementation reuse.

Preconditions

• The registry exists.
• The capability candidate has at least a name and rough summary.

Main Flow

1. Actor creates a new capability entry.
2. Actor assigns a stable capability ID.
3. Actor provides name, summary, owner, and initial maturity values.
4. Actor links available evidence, if any.
5. Registry validates required fields.
6. Registry stores the capability entry.

Acceptance Criteria

• The capability has a unique ID.
• The capability is findable by name and summary.
• The capability has initial Discovery, Availability, Completeness, and Reliability values.
• Missing evidence is represented explicitly rather than hidden.

Scoring

Dimension	Score
Planning Value	2
Implementation Value	1
Governance Value	2
MVP Relevance	2
Complexity	1
Automation Potential	2

---

UC-RS-002 — Classify Capability Discovery Maturity

Primary Actor: Capability Owner
Supporting Actors: Product Planner, Architect, Reviewer

Intent

Assess how reusable a capability is for planning.

Trigger

A capability is created, reviewed, promoted, or prepared for roadmap use.

Main Flow

1. Actor reviews capability documentation.
2. Actor checks evidence against Discovery levels D0–D7.
3. Actor selects the highest defensible level.
4. Actor records rationale and supporting evidence.
5. Reviewer validates the classification if required.

Acceptance Criteria

• Discovery level is assigned using the standard definitions.
• Evidence supports the selected level.
• Missing evidence is visible.
• Promotion rationale is documented.

Discovery Levels

Level	Name
D0	Named
D1	Described
D2	Bounded
D3	Explored
D4	Researched
D5	Grounded
D6	Exhaustive
D7	Generalized

---

UC-RS-003 — Classify Capability Availability

Primary Actor: Capability Owner
Supporting Actors: Implementer, Platform Owner, Reviewer

Intent

Assess how directly consumers can consume a capability for implementation or operation.

Trigger

A new artifact becomes available: prototype, source module, CLI, SDK, service, container, managed platform service, or cloud offering.

Main Flow

1. Actor reviews available artifacts.
2. Actor checks evidence against Availability levels A0–A7.
3. Actor selects current and target availability levels.
4. Actor links artifacts and access instructions.
5. Registry exposes the availability to consumers.

Acceptance Criteria

• Current Availability level is clear.
• Target Availability level may be stated separately.
• Consumption mode is visible.
• Consumers can find the referenced artifact or understand that none exists yet.

Availability Levels

Level	Name
A0	Informational Only
A1	Experimental Prototype
A2	Source Module / Library
A3	Command-Line Package
A4	Service API / SDK
A5	Containerized Service
A6	Managed Platform Capability
A7	External Cloud Service Offering

---

UC-RS-004 — Search for Capabilities by Planning Need

Primary Actor: Product Planner
Supporting Actors: Architect, Agentic Planning Agent

Intent

Find capabilities relevant to a product idea, roadmap theme, MVP candidate, or enhancement area.

Main Flow

1. Actor enters a planning need or topic.
2. Registry searches names, summaries, intents, use cases, and related capabilities.
3. Registry returns candidate capabilities.
4. Actor filters by Discovery maturity, domain, tags, and relations.
5. Actor selects capabilities for planning reuse.

Acceptance Criteria

• Results include maturity vectors.
• Results distinguish planning-ready and weakly described capabilities.
• Results show related capabilities and known gaps.

Example

Search:

multi-tenant feature control for agents and users

Possible result:

capability.feature-control.evaluate — D5 / A4 / C3 / R3

---

UC-RS-005 — Search for Capabilities by Consumption Mode

Primary Actor: Implementer
Supporting Actors: Agentic Coding Agent

Intent

Find capabilities available in a usable form for implementation.

Main Flow

1. Actor specifies desired consumption mode.
2. Registry filters by Availability level.
3. Actor reviews available artifacts.
4. Actor selects suitable capability for implementation reuse.

Example Filters

availability:
  minimum: A3
consumption_modes:
  - cli
  - sdk
  - service-api

Acceptance Criteria

• Results distinguish informational entries from consumable artifacts.
• Artifacts include links or paths.
• Limitations and reliability evidence are visible.

---

UC-RS-006 — Compare Capability Candidates

Primary Actor: Architect
Supporting Actors: Product Planner, Implementer

Intent

Compare several capabilities to decide whether to reuse, extend, merge, replace, or build new.

Main Flow

1. Actor selects two or more candidate capabilities.
2. Registry displays maturity vectors, scope, availability, completeness, reliability, and relations.
3. Actor reviews overlaps and differences.
4. Actor records selection decision or follow-up action.

Acceptance Criteria

• Comparison exposes Discovery and Availability differences.
• Completeness and Reliability are shown separately.
• Duplicate and overlapping scope is visible.

---

UC-RS-007 — Identify Reuse Gaps for MVP Planning

Primary Actor: Product Planner
Supporting Actors: Architect, Capability Owner

Intent

Identify which capabilities are ready for MVP reuse and which require development, research, or clarification.

Main Flow

1. Actor selects an MVP concept or product theme.
2. Registry maps related capabilities.
3. Registry shows current maturity and target maturity.
4. Actor identifies gaps.
5. Actor exports capability work items or planning notes.

Acceptance Criteria

• Registry distinguishes planning gaps from implementation gaps.
• D-level gaps and A-level gaps are visible separately.
• Capabilities with low Completeness or Reliability are flagged.

---

UC-RS-008 — Track SCOPE vs INTENT Completeness

Primary Actor: Product Owner
Supporting Actors: Consumer, Capability Owner

Intent

Assess whether the current scope of a capability satisfies its declared intent and consumer expectations.

Main Flow

1. Actor reviews declared INTENT.
2. Actor reviews current SCOPE.
3. Actor reviews satisfied expectations, broken expectations, and out-of-scope expectations.
4. Actor assigns Completeness level C0–C6.
5. Actor records evidence and confidence.

Acceptance Criteria

• Completeness is based on INTENT, SCOPE, and consumer expectations.
• Broken expectations are recorded.
• Out-of-scope expectations are classified explicitly.

Completeness Levels

Level	Name
C0	Unknown
C1	Fragmentary
C2	Partial
C3	Functional Core
C4	Broadly Covered
C5	Expectation Complete
C6	Saturated

---

UC-RS-009 — Track Reliability Evidence

Primary Actor: Capability Owner
Supporting Actors: Consumer, Platform Owner, Reviewer

Intent

Capture consumer-relevant quality evidence for a capability.

Main Flow

1. Actor collects quality evidence.
2. Actor groups evidence by bugs, support feedback, operational evidence, consumer feedback, compatibility evidence, and integration evidence.
3. Actor assigns Reliability level R0–R6.
4. Registry exposes reliability risks and confidence.

Acceptance Criteria

• Reliability is assessed from consumer-relevant evidence.
• Bugs, ratings, incidents, and support signals may contribute.
• Reliability is not confused with Completeness.

Reliability Levels

Level	Name
R0	Unknown
R1	Fragile
R2	Tolerable
R3	Usable
R4	Dependable
R5	Trusted
R6	Proven

---

UC-RS-010 — Record Broken Consumer Expectations

Primary Actor: Consumer
Supporting Actors: Product Owner, Capability Owner

Intent

Capture cases where consumers expected the capability to do something that it did not do.

Main Flow

1. Consumer reports a broken expectation.
2. Registry links the expectation to a capability.
3. Product Owner classifies the expectation as in-scope, out-of-scope, unclear, or future extension.
4. Completeness evidence is updated.
5. Follow-up work may be created.

Acceptance Criteria

• Broken expectation is preserved as evidence.
• Classification is explicit.
• Completeness level can be adjusted based on repeated patterns.

---

UC-RS-011 — Promote a Capability to Higher Discovery Maturity

Primary Actor: Capability Owner
Supporting Actors: Reviewer

Intent

Raise the Discovery maturity of a capability when sufficient evidence exists.

Main Flow

1. Actor identifies a target Discovery level.
2. Actor checks required evidence.
3. Actor adds missing documentation or links.
4. Actor updates maturity level.
5. Reviewer accepts or rejects promotion.

Acceptance Criteria

• Promotion has evidence.
• The registry stores promotion history.
• Review comments remain traceable.

---

UC-RS-012 — Promote a Capability to Higher Availability

Primary Actor: Implementer
Supporting Actors: Capability Owner, Platform Owner

Intent

Raise Availability maturity when a capability becomes consumable through a richer mode.

Example Promotion Paths

A0 → A1: add prototype
A1 → A2: extract source module
A2 → A3: publish CLI
A3 → A4: expose API/SDK
A4 → A5: package as containerized service
A5 → A6: operate as managed platform capability
A6 → A7: offer as external cloud service

Acceptance Criteria

• Availability level matches actual consumer access.
• Target and current availability may differ.
• Consumers receive clear usage guidance.

---

UC-RS-013 — Use Registry Metadata in Agentic Coding

Primary Actor: Agentic Coding Agent
Supporting Actors: Implementer, Capability Owner

Intent

Allow coding agents to find existing capabilities before creating new code.

Main Flow

1. Agent receives a development task.
2. Agent searches registry for relevant capabilities.
3. Agent evaluates availability and reliability.
4. Agent reuses an existing capability or explains why not.
5. Agent may suggest updates to the registry.

Acceptance Criteria

• Machine-readable registry export exists.
• Capability entries include enough metadata for automated selection.
• Agent can distinguish reusable implementation from planning-only entries.

---

UC-RS-014 — Generate Capability Reuse Recommendations

Primary Actor: Architect
Supporting Actors: Agentic Planning Agent

Intent

Generate recommendations for which capabilities should be reused, improved, ignored, or created.

Main Flow

1. Actor provides project context.
2. Registry finds candidate capabilities.
3. Recommendation engine applies maturity, completeness, reliability, and relations.
4. Registry outputs recommendations with rationale.

Acceptance Criteria

• Recommendations include evidence and uncertainty.
• Recommendations do not treat maturity as quality alone.
• Recommendations distinguish planning reuse from implementation reuse.

---

UC-RS-015 — Detect Duplicate or Overlapping Capabilities

Primary Actor: Governance Maintainer
Supporting Actors: Architect, Capability Owner

Intent

Find capabilities that may represent the same or overlapping reusable behavior.

Main Flow

1. Registry analyzes names, descriptions, scopes, relations, and use cases.
2. Registry flags possible overlap.
3. Maintainer reviews candidates.
4. Maintainer merges, links, renames, or marks as distinct.

Acceptance Criteria

• Potential overlap is visible.
• Distinct variants can coexist when justified.
• Merged or deprecated capabilities remain traceable.

---

UC-RS-016 — Maintain Capability Relations

Primary Actor: Architect
Supporting Actors: Capability Owner

Intent

Maintain graph relations between capabilities.

Relation Types

relations:
  depends_on: []
  supports: []
  replaces: []
  replaced_by: []
  specializes: []
  generalizes: []
  related_to: []
  conflicts_with: []

Acceptance Criteria

• Relations are typed.
• Cycles are detected where relevant.
• Dependency and reuse graphs can be generated.

---

UC-RS-017 — Review Capability Entry Quality

Primary Actor: Reviewer
Supporting Actors: Governance Maintainer, Capability Owner

Intent

Check whether a capability entry is clear, evidence-based, and useful for reuse.

Main Flow

1. Reviewer selects registry entry.
2. Reviewer checks required fields and maturity claims.
3. Reviewer comments on missing evidence, unclear scope, or poor naming.
4. Capability Owner updates entry.
5. Reviewer approves entry quality.

Acceptance Criteria

• Review history is traceable.
• Registry supports status such as draft, reviewed, approved, deprecated.
• Maturity claims can be challenged.

---

UC-RS-018 — Publish a Human-Readable Capability Catalog

Primary Actor: Platform Owner
Supporting Actors: Product Planner, Architect

Intent

Publish a browsable catalog for humans.

Main Flow

1. Actor selects registry scope.
2. Registry renders catalog pages.
3. Catalog groups capabilities by domain, maturity, availability, owner, and relations.
4. Consumers browse and filter.

Acceptance Criteria

• Catalog is readable without knowing schema internals.
• Maturity vectors are visible.
• Consumers can navigate to evidence and artifacts.

---

UC-RS-019 — Publish a Machine-Readable Registry Export

Primary Actor: Agentic Coding Agent
Supporting Actors: Implementer, Governance Maintainer

Intent

Expose registry data for automation, agents, CLIs, and integration tools.

Main Flow

1. Registry validates entries.
2. Registry exports JSON, YAML, or other supported machine-readable formats.
3. Consumers fetch or import the export.
4. Consumers use metadata for planning or implementation selection.

Acceptance Criteria

• Export format is documented.
• Schema validation is available.
• Entries include stable IDs and maturity fields.

---

UC-RS-020 — Select Capabilities for Platformization

Primary Actor: Platform Owner
Supporting Actors: Architect, Product Owner

Intent

Identify capabilities that should become shared platform capabilities.

Main Flow

1. Actor filters capabilities with high reuse potential.
2. Actor reviews Discovery, Availability, Completeness, and Reliability.
3. Actor checks known consumers and expected demand.
4. Actor selects platformization candidates.
5. Registry records target Availability, usually A5 or A6.

Acceptance Criteria

• Selection is evidence-based.
• Target availability is explicit.
• Capability gaps are visible before platformization begins.

---

UC-RS-021 — Identify Capabilities Ready for Commercial Offering

Primary Actor: Product Owner
Supporting Actors: Platform Owner, Architect

Intent

Find capabilities that may become external cloud service offerings or commercial API products.

Main Flow

1. Actor filters capabilities with high Discovery and high consumer value.
2. Actor reviews Availability target A7.
3. Actor checks Completeness and Reliability evidence.
4. Actor identifies packaging, billing, support, and governance gaps.
5. Actor records commercial offering candidate status.

Acceptance Criteria

• Commercial readiness is not inferred from implementation alone.
• Completeness and Reliability are considered before externalization.
• Missing support and governance requirements are visible.

---

UC-RS-022 — Track Capability Evolution Over Time

Primary Actor: Capability Owner
Supporting Actors: Governance Maintainer

Intent

Track how capability maturity, availability, completeness, and reliability change over time.

Main Flow

1. Registry stores maturity history.
2. Actor records promotion, demotion, or evidence change.
3. Registry can generate timeline or changelog.
4. Consumers can inspect current and historical state.

Acceptance Criteria

• Maturity changes are timestamped.
• Previous levels remain auditable.
• Rationale and evidence links are preserved.

---

UC-RS-023 — Validate Registry Entries Against Schema

Primary Actor: Governance Maintainer
Supporting Actors: Agentic Coding Agent

Intent

Ensure registry entries conform to expected structure.

Main Flow

1. Actor runs validation.
2. Registry schema checks required fields, enum values, relation references, and evidence structure.
3. Validation reports errors and warnings.
4. Actor or agent repairs entries.

Acceptance Criteria

• Invalid maturity values are rejected.
• Broken relation references are detected.
• Required registry fields are enforced.

---

UC-RS-024 — Produce Capability Maturity Reports

Primary Actor: Governance Maintainer
Supporting Actors: Product Planner, Platform Owner

Intent

Generate reports that summarize registry maturity and reuse readiness.

Main Flow

1. Actor selects reporting scope.
2. Registry aggregates capability maturity vectors.
3. Registry identifies strong, weak, missing, overlapping, and high-potential capabilities.
4. Report is exported as Markdown, JSON, or dashboard data.

Acceptance Criteria

• Reports distinguish internal maturity and external evidence.
• Reports identify planning-ready and implementation-ready capabilities separately.
• Reports can guide roadmap and platform decisions.

8. MVP Use Cases

The initial MVP should prioritize use cases that establish the registry as a useful reuse surface.

Recommended MVP set:

ID	Title	Reason
UC-RS-001	Register a New Capability	Core registry function.
UC-RS-002	Classify Capability Discovery Maturity	Enables planning reuse.
UC-RS-003	Classify Capability Availability	Enables implementation reuse.
UC-RS-004	Search for Capabilities by Planning Need	Makes registry useful to planners.
UC-RS-005	Search for Capabilities by Consumption Mode	Makes registry useful to implementers.
UC-RS-006	Compare Capability Candidates	Enables reuse decision-making.
UC-RS-013	Use Registry Metadata in Agentic Coding	Supports agentic development workflows.
UC-RS-019	Publish a Machine-Readable Registry Export	Enables automation and integration.
UC-RS-023	Validate Registry Entries Against Schema	Keeps registry data usable.

9. Suggested Capability Entry Skeleton

id: capability.example
name: Example Capability
summary: A short explanation of what the capability enables.
owner: team-or-person
status: draft

maturity:
  discovery:
    current: D1
    target: D5
  availability:
    current: A0
    target: A3

external_evidence:
  completeness:
    level: C0
    confidence: low
    satisfied_expectations: []
    broken_expectations: []
    out_of_scope_expectations: []
  reliability:
    level: R0
    confidence: low
    evidence: []

intent:
  statement: >
    Explain what this capability is intended to make possible.

scope:
  includes: []
  excludes: []
  assumptions: []

availability:
  current_artifacts: []
  target_artifacts: []
  consumption_modes: []

relations:
  depends_on: []
  supports: []
  related_to: []

use_cases: []

evidence:
  research_memos: []
  design_notes: []
  implementation_refs: []
  issue_refs: []
  feedback_refs: []

10. Open Questions

• Should reuse-surface store registry entries as individual Markdown files, YAML files, JSON documents, or a hybrid format?
• Should human-readable Markdown be generated from canonical YAML/JSON, or should Markdown with frontmatter be canonical?
• How strict should maturity promotion review be in early repo usage?
• Should the registry support multiple scopes, such as personal, company, platform, product, and public ecosystem?
• Should external evidence be manually curated first and automated later, or should issue/star/usage connectors be part of the early design?
• Should relation graphs be represented directly in registry files or derived during validation?

11. Success Criteria

reuse-surface succeeds when:

• Planners can find capabilities relevant to roadmap and MVP work.
• Implementers can find capabilities available for reuse.
• Agents can use registry metadata to avoid reinventing already available capabilities.
• Capability maturity is visible without being confused with implementation quality alone.
• Completeness and Reliability incorporate consumer evidence.
• Capability owners can promote capabilities based on evidence.
• Registry data can be validated, exported, searched, and reviewed.