diff --git a/specs/ProductRequirementsDocument.md b/specs/ProductRequirementsDocument.md new file mode 100755 index 0000000..67e4646 --- /dev/null +++ b/specs/ProductRequirementsDocument.md @@ -0,0 +1,537 @@ +# 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: + +1. **What reusable capabilities do we know about?** +2. **How mature are they for planning?** +3. **How are they available for implementation or operation?** +4. **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: + +```text +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: + +```text +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: + +```yaml +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: + +1. `INTENT.md`. +2. `ProductRequirementsDefinition.md`. +3. `CapabilityMaturityStandard.md`. +4. A first capability entry template. +5. A machine-readable schema draft. +6. A small sample registry with at least three capabilities. +7. A generated or manually maintained capability index. +8. Basic validation rules for required fields. +9. Basic search/filter guidance. +10. 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 + +1. Should the canonical registry format be Markdown with YAML front matter, standalone YAML, JSON, or a hybrid? +2. Should capability IDs follow reverse-DNS style, repo-local style, or domain-based naming? +3. How strict should validation be for low-maturity entries? +4. Should evidence confidence be scored numerically or qualitatively? +5. How should consumer expectations be gathered and normalized? +6. How should duplicate or overlapping capabilities be merged? +7. 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.