Files

tegwick c8bf65f1bd ProductRequirementsDocument established

2026-06-15 00:24:26 +02:00

16 KiB

Executable File

Raw Blame History

Product Requirements Definition: reuse-surface

Repository: reuse-surface
Artifact: ProductRequirementsDefinition.md
Status: Draft 0.1
Purpose: Define the product requirements for a capability registry that makes reusable capabilities visible, assessable, comparable, and consumable across repositories, products, agents, and platform environments.

1. Product Intent

reuse-surface provides a registry-centric surface for discovering, assessing, and reusing capabilities.

The product exists to answer four practical questions:

What reusable capabilities do we know about?
How mature are they for planning?
How are they available for implementation or operation?
How complete and reliable are they from the consumer perspective?

A capability that is not registered is considered invisible for reuse within the scope of this product. The registry therefore acts as the boundary of practical reuse awareness.

2. Core Product Hypothesis

Reusable capabilities are often hidden in repositories, documents, workflows, prototypes, tools, services, or operational practices. Without a registry, they are rediscovered, duplicated, inconsistently named, and poorly evaluated.

If capabilities are registered with clear discovery maturity, availability maturity, completeness evidence, reliability evidence, and relations to other capabilities, then humans and agents can plan and implement more effectively by reusing existing capability knowledge and delivery artifacts.

3. Target Users

User	Need
Product planner	Find capabilities suitable for roadmap, MVP, and enhancement planning.
Architect	Understand capability boundaries, dependencies, alternatives, and maturity.
Developer	Discover reusable implementation artifacts such as modules, CLIs, SDKs, services, or containers.
Platform operator	Identify capabilities ready for managed internal platform use.
Agentic coding assistant	Query capability metadata to avoid duplication and select existing reusable building blocks.
Portfolio owner	See capability coverage, gaps, overlap, investment candidates, and reuse potential.
Capability owner	Maintain registry entries and track maturity, completeness, and reliability over time.

4. Scope

4.1 In Scope

reuse-surface shall provide:

A canonical capability registry format.
A capability maturity model using four dimensions:
- Discovery maturity.
- Availability maturity.
- Completeness.
- Reliability.
Registry entries for reusable capabilities.
Human-readable Markdown views.
Machine-readable structured metadata.
Search, filtering, and comparison mechanisms.
Capability relationship mapping.
Evidence references for maturity assessments.
Lightweight workflows for adding, updating, reviewing, and promoting capabilities.
Support for humans and agents as registry consumers.

4.2 Out of Scope for Initial Product

reuse-surface shall not initially provide:

Full implementation hosting for capabilities.
A package registry replacement.
A cloud marketplace.
Deep runtime observability collection.
Automated quality certification without human review.
Full dependency graph analysis from source code.
A complete UI platform.

These may be future extensions.

5. Conceptual Model

5.1 Capability

A capability is a named, bounded, reusable unit of behavior or know-how that can support planning, implementation, operation, or product composition.

Capabilities may exist as concepts, research assets, prototypes, libraries, CLIs, SDKs, services, containers, platform capabilities, or cloud offerings.

5.2 Registry Entry

A registry entry is the authoritative record of a capability within reuse-surface.

A registry entry shall include:

Stable capability ID.
Name and summary.
Discovery maturity.
Availability maturity.
Completeness assessment.
Reliability assessment.
Current and target maturity levels.
Scope information.
Evidence references.
Consumer guidance.
Relationships to other capabilities.

5.3 Capability Reuse Surface

The reuse surface is the practical interface through which humans and agents discover, compare, and consume capability knowledge.

The reuse surface includes:

Markdown files.
Structured registry files.
Indexes.
Generated views.
Searchable metadata.
Agent-readable summaries.

6. Maturity Dimensions

reuse-surface shall use four primary assessment dimensions.

Dimension	Type	Question
Discovery	Internal	How reusable is this capability for planning?
Availability	Internal	How can consumers access or consume it?
Completeness	External	How well does current scope satisfy intent and consumer expectations?
Reliability	External	How consistently does it satisfy consumer-relevant quality expectations?

The canonical maturity vector shall be written as:

D5 / A4 / C3 / R3

7. Discovery Maturity

Discovery maturity measures planning reuse.

Level	Name	Meaning
D0	Named	Capability is visible in the registry.
D1	Described	Capability has meaning, intent, and context.
D2	Bounded	Scope, inclusions, exclusions, and neighboring capabilities are defined.
D3	Explored	Obvious relevant aspects have been investigated.
D4	Researched	Prior art, alternatives, products, standards, and tradeoffs have been deeply examined.
D5	Grounded	Concrete use cases, actors, scenarios, and prioritization criteria are documented.
D6	Exhaustive	Use-case and scope exploration has likely reached saturation.
D7	Generalized	Capability has become a reusable planning primitive beyond one repo, product, or domain.

8. Availability Maturity

Availability maturity measures how the capability is available to consumers.

Level	Name	Consumer reuse mode
A0	Informational Only	Read and plan.
A1	Experimental Prototype	Learn and experiment.
A2	Source Module / Library	Import and build with code.
A3	Command-Line Package	Automate via CLI.
A4	Service API / SDK	Integrate into applications.
A5	Containerized Service	Deploy and operate.
A6	Managed Platform Capability	Consume as internal platform service.
A7	External Cloud Service Offering	Consume as public or commercial service.

Availability maturity does not primarily assess internal implementation quality. It describes the consumption form.

9. Completeness

Completeness measures how well the current scope satisfies declared intent and consumer expectations.

Level	Name	Meaning
C0	Unknown	No meaningful evidence about scope versus intent.
C1	Fragmentary	Only isolated parts of the expected capability are present.
C2	Partial	Some important expectations are satisfied, but major gaps remain.
C3	Functional Core	The central expected use case works, but variants and edge cases are incomplete.
C4	Broadly Covered	Most common consumer expectations are satisfied; gaps are known and bounded.
C5	Expectation Complete	The declared intent is substantially fulfilled for known consumer expectations.
C6	Saturated	Further consumer discovery rarely reveals missing scope; new requests are mostly extensions or variants.

Completeness is based on evidence such as satisfied expectations, broken expectations, requested extensions, scope notes, and intent alignment.

10. Reliability

Reliability measures how consistently the capability satisfies consumer-relevant quality expectations in real or realistic use.

Level	Name	Meaning
R0	Unknown	No meaningful evidence about consumer-relevant quality.
R1	Fragile	Frequently breaks, surprises, or disappoints consumers.
R2	Tolerable	Works in some situations, but consumers must expect friction.
R3	Usable	Works reliably for normal use, with known limitations.
R4	Dependable	Consumers can rely on it for important workflows.
R5	Trusted	Strong consumer confidence; failures are rare and well handled.
R6	Proven	Reliability is demonstrated across broad, repeated, and demanding use.

Reliability evidence may include bug reports, incidents, support tickets, failed integrations, ratings, retention, usage history, compatibility experience, and consumer reviews.

11. Core Functional Requirements

FR-1: Capability Registry

The product shall provide a structured registry for capability entries.

Each entry shall support:

Stable ID.
Name.
Summary.
Owner.
Status.
Current maturity vector.
Target maturity vector.
Scope and intent information.
Evidence references.
Consumer guidance.
Capability relationships.

FR-2: Markdown-First Authoring

The product shall support Markdown-first authoring for humans.

Registry content should remain understandable and maintainable in plain text.

FR-3: Machine-Readable Metadata

The product shall support machine-readable metadata for agents, scripts, and generated views.

Supported formats should include YAML front matter, standalone YAML, JSON, or a similarly simple structured representation.

FR-4: Capability Search

The product shall support finding capabilities by:

Name.
ID.
Summary text.
Maturity levels.
Availability mode.
Owner.
Domain.
Related capability.
Consumer type.
Evidence type.

FR-5: Capability Comparison

The product shall support comparing capabilities by maturity vector and registry metadata.

Example comparison questions:

Which capabilities are D5 or higher but only A0 or A1?
Which capabilities are available as CLI tools?
Which capabilities are broadly covered but fragile?
Which capabilities are good candidates for platformization?

FR-6: Evidence References

The product shall allow registry entries to cite evidence.

Evidence may include:

Research memos.
Use case catalog entries.
PRDs.
FRS documents.
Source modules.
CLI packages.
SDKs.
Service APIs.
Containers.
Deployment manifests.
Bug reports.
Support tickets.
Ratings.
Consumer feedback.

FR-7: Capability Relations

The product shall support capability graph relationships.

Required relation types:

depends_on
supports
used_by
related_to
specializes
generalizes
replaces
wraps

FR-8: Current and Target State

The product shall distinguish current state and target state.

Each maturity dimension should support:

Current level.
Target level.
Rationale.
Evidence.
Confidence.

FR-9: Consumer Guidance

Each capability entry should explain how consumers can reuse the capability.

Guidance may include:

Recommended use.
Unsafe use.
Known limitations.
Integration notes.
Responsible owner.
Preferred alternative.
Migration guidance.

FR-10: Agent-Friendly Queries

The product shall support agentic consumers that need to answer questions such as:

Does a capability already exist for this need?
Which implementation artifact should be reused?
What maturity and risk should be considered?
Which capability should be extended rather than duplicated?
Which registry entries are incomplete or stale?

12. Non-Functional Requirements

NFR-1: Low Friction

Registry contribution must be lightweight enough to capture low-maturity capabilities early.

NFR-2: Human and Agent Readability

All core information must be usable by both human readers and LLM/code agents.

NFR-3: Git-Friendly

The registry must work well in Git:

Plain text files.
Diffable changes.
Reviewable pull requests.
Stable IDs.
Explicit evidence links.

NFR-4: Evolvability

The schema and maturity model must allow extension without breaking existing registry entries unnecessarily.

NFR-5: Traceability

Assessments must be traceable to evidence where possible.

NFR-6: No False Precision

The product should support approximate and confidence-qualified assessments rather than pretending all maturity scores are exact.

13. Initial Repository Structure

Recommended initial structure:

reuse-surface/
├── INTENT.md
├── ProductRequirementsDefinition.md
├── standards/
│   └── CapabilityMaturityStandard.md
├── registry/
│   ├── README.md
│   ├── capabilities/
│   │   └── example.capability.md
│   └── indexes/
│       └── capabilities.yaml
├── schemas/
│   └── capability.schema.yaml
├── templates/
│   └── capability-entry.template.md
├── research/
│   └── README.md
└── tools/
    └── README.md

14. Capability Entry Template

A minimal capability entry should look like this:

id: capability.example.name
name: Example Capability
summary: Short description of the capability.
owner: unknown
status: draft

maturity:
  discovery:
    current: D1
    target: D5
    confidence: low
  availability:
    current: A0
    target: A3
    confidence: low
  completeness:
    current: C0
    target: C4
    confidence: low
  reliability:
    current: R0
    target: R3
    confidence: low

intent: >
  Explain what the capability is meant to make possible.

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

availability:
  current_artifacts: []
  target_artifacts: []
  consumer_modes: []

evidence:
  discovery: []
  availability: []
  completeness: []
  reliability: []

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

consumer_guidance:
  recommended_for: []
  not_recommended_for: []
  known_limitations: []

15. MVP Requirements

The MVP shall include:

INTENT.md.
ProductRequirementsDefinition.md.
CapabilityMaturityStandard.md.
A first capability entry template.
A machine-readable schema draft.
A small sample registry with at least three capabilities.
A generated or manually maintained capability index.
Basic validation rules for required fields.
Basic search/filter guidance.
Agent instructions for querying and updating the registry.

16. MVP Acceptance Criteria

The MVP is acceptable when a human or agent can:

Add a new capability at D0/A0/C0/R0 with minimal friction.
Promote a capability through discovery levels by attaching evidence.
Identify how a capability is currently available to consumers.
Record consumer expectations and broken expectations.
Record consumer reliability evidence.
Search for capabilities by maturity and availability.
Compare candidate capabilities for reuse.
Avoid creating a duplicate capability because an existing one is discoverable.

17. Future Enhancements

Potential future enhancements include:

CLI tool for registry validation and querying.
Static site generator for registry browsing.
Capability graph visualization.
Integration with issue trackers.
Integration with package registries.
Integration with service catalogs.
Automated evidence ingestion.
Consumer feedback capture workflows.
Capability duplicate detection.
Agentic planning workflows that use registry entries as planning primitives.
Registry federation across organizations or repos.

18. Open Questions

Should the canonical registry format be Markdown with YAML front matter, standalone YAML, JSON, or a hybrid?
Should capability IDs follow reverse-DNS style, repo-local style, or domain-based naming?
How strict should validation be for low-maturity entries?
Should evidence confidence be scored numerically or qualitatively?
How should consumer expectations be gathered and normalized?
How should duplicate or overlapping capabilities be merged?
Should reuse-surface include a CLI from the start or remain document-first for the MVP?

19. Guiding Principle

The capability registry should not primarily describe what exists. It should describe what can be reused, at which confidence level, for which kind of work.

reuse-surface succeeds when it makes reuse easier than rediscovery.

16 KiB Executable File Raw Blame History