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:

```text
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:

```text
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:

```text
multi-tenant feature control for agents and users
```

Possible result:

```text
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

```yaml
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

```text
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

```yaml
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

```yaml
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.