496 lines
7.1 KiB
Markdown
496 lines
7.1 KiB
Markdown
|
ProductRequirementsSpecV0.1
|
|||
|
|
|
|||
|
|
*Repository Ability Registry Requirements*
|
|||
|
|
|
|||
|
|
# **Product Requirements Document (PRD)**
|
|||
|
|
|
|||
|
|
## **Repository Ability Registry (v0.1)**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 1. **Purpose**
|
|||
|
|
|
|||
|
|
The **Repository Ability Registry** provides a structured, inspectable orientation layer for code repositories by mapping them from **abilities → capabilities → features → implementation → evidence**.
|
|||
|
|
|
|||
|
|
It enables developers, architects, and agents to:
|
|||
|
|
|
|||
|
|
* understand what a repository is useful for
|
|||
|
|
* inspect how it implements that usefulness
|
|||
|
|
* compare repositories based on real functionality
|
|||
|
|
* search repositories using natural language
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 2. **Problem Statement**
|
|||
|
|
|
|||
|
|
Modern code repositories suffer from **orientation opacity**:
|
|||
|
|
|
|||
|
|
* usefulness is unclear from structure alone
|
|||
|
|
* README files are incomplete or misleading
|
|||
|
|
* functionality is scattered across code
|
|||
|
|
* reuse decisions rely on tribal knowledge
|
|||
|
|
|
|||
|
|
This results in:
|
|||
|
|
|
|||
|
|
* wasted time exploring repositories
|
|||
|
|
* duplicated work
|
|||
|
|
* poor architectural decisions
|
|||
|
|
* low reuse of existing assets
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 3. **Goals**
|
|||
|
|
|
|||
|
|
## 3.1 Primary Goal
|
|||
|
|
|
|||
|
|
> Enable users to **register a repository and understand its usefulness within minutes** via an inspectable ability map.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3.2 Secondary Goals
|
|||
|
|
|
|||
|
|
* enable **natural language search** across repositories
|
|||
|
|
* provide **traceability from abstraction to code**
|
|||
|
|
* establish a **foundation for proof-of-ability integration**
|
|||
|
|
* support both **human and agent interaction**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3.3 Non-Goals (v0.1)
|
|||
|
|
|
|||
|
|
* full automated benchmarking
|
|||
|
|
* advanced ontology enforcement
|
|||
|
|
* marketplace features
|
|||
|
|
* monetization features
|
|||
|
|
* full CI/CD integration
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 4. **Users**
|
|||
|
|
|
|||
|
|
## 4.1 Developer / Architect
|
|||
|
|
|
|||
|
|
* needs to find reusable functionality
|
|||
|
|
* needs to understand unfamiliar repos quickly
|
|||
|
|
|
|||
|
|
## 4.2 Repository Owner
|
|||
|
|
|
|||
|
|
* wants their repo to be understandable and discoverable
|
|||
|
|
|
|||
|
|
## 4.3 Registry Curator
|
|||
|
|
|
|||
|
|
* ensures quality and correctness of extracted data
|
|||
|
|
|
|||
|
|
## 4.4 Agent / Automation
|
|||
|
|
|
|||
|
|
* queries registry programmatically
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 5. **Core Concepts**
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
Ability = why the repository is useful
|
|||
|
|
Capability = what behavior it provides
|
|||
|
|
Feature = how the behavior is exposed/implemented
|
|||
|
|
Evidence = why the capability can be trusted
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 6. **Product Scope (MVP)**
|
|||
|
|
|
|||
|
|
## 6.1 Included
|
|||
|
|
|
|||
|
|
* repository registration
|
|||
|
|
* repository analysis (semi-automated)
|
|||
|
|
* ability/capability/feature extraction (assisted)
|
|||
|
|
* human review and correction
|
|||
|
|
* searchable registry
|
|||
|
|
* inspectable repository view
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6.2 Excluded
|
|||
|
|
|
|||
|
|
* automated full-code understanding engine
|
|||
|
|
* distributed indexing
|
|||
|
|
* deep static analysis
|
|||
|
|
* real-time synchronization
|
|||
|
|
* full dependency graph modeling
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 7. **Functional Requirements**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.1 Repository Registration
|
|||
|
|
|
|||
|
|
### FR-01
|
|||
|
|
|
|||
|
|
User can register a repository via Git URL.
|
|||
|
|
|
|||
|
|
### FR-02
|
|||
|
|
|
|||
|
|
System validates repository access.
|
|||
|
|
|
|||
|
|
### FR-03
|
|||
|
|
|
|||
|
|
System stores repository metadata.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.2 Repository Analysis
|
|||
|
|
|
|||
|
|
### FR-04
|
|||
|
|
|
|||
|
|
System clones or accesses repository contents.
|
|||
|
|
|
|||
|
|
### FR-05
|
|||
|
|
|
|||
|
|
System extracts:
|
|||
|
|
|
|||
|
|
* languages
|
|||
|
|
* structure
|
|||
|
|
* interfaces (API, CLI, etc.)
|
|||
|
|
* documentation files
|
|||
|
|
* tests
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.3 Ability Extraction
|
|||
|
|
|
|||
|
|
### FR-06
|
|||
|
|
|
|||
|
|
System generates candidate abilities based on:
|
|||
|
|
|
|||
|
|
* README
|
|||
|
|
* documentation
|
|||
|
|
* examples
|
|||
|
|
|
|||
|
|
### FR-07
|
|||
|
|
|
|||
|
|
Each ability includes:
|
|||
|
|
|
|||
|
|
* name
|
|||
|
|
* description
|
|||
|
|
* confidence
|
|||
|
|
* source references
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.4 Capability Extraction
|
|||
|
|
|
|||
|
|
### FR-08
|
|||
|
|
|
|||
|
|
System identifies candidate capabilities from:
|
|||
|
|
|
|||
|
|
* modules
|
|||
|
|
* APIs
|
|||
|
|
* tests
|
|||
|
|
* code structure
|
|||
|
|
|
|||
|
|
### FR-09
|
|||
|
|
|
|||
|
|
Capabilities include:
|
|||
|
|
|
|||
|
|
* inputs
|
|||
|
|
* outputs
|
|||
|
|
* linked abilities
|
|||
|
|
* description
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.5 Feature Extraction
|
|||
|
|
|
|||
|
|
### FR-10
|
|||
|
|
|
|||
|
|
System identifies concrete features:
|
|||
|
|
|
|||
|
|
* endpoints
|
|||
|
|
* CLI commands
|
|||
|
|
* modules
|
|||
|
|
* configuration interfaces
|
|||
|
|
|
|||
|
|
### FR-11
|
|||
|
|
|
|||
|
|
Each feature includes:
|
|||
|
|
|
|||
|
|
* type
|
|||
|
|
* implementation location
|
|||
|
|
* linked capability
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.6 Evidence Linking
|
|||
|
|
|
|||
|
|
### FR-12
|
|||
|
|
|
|||
|
|
System identifies potential evidence:
|
|||
|
|
|
|||
|
|
* tests
|
|||
|
|
* examples
|
|||
|
|
* benchmarks
|
|||
|
|
* docs
|
|||
|
|
|
|||
|
|
### FR-13
|
|||
|
|
|
|||
|
|
User can manually attach evidence to capabilities.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.7 Review and Curation
|
|||
|
|
|
|||
|
|
### FR-14
|
|||
|
|
|
|||
|
|
User can review extracted abilities, capabilities, features.
|
|||
|
|
|
|||
|
|
### FR-15
|
|||
|
|
|
|||
|
|
User can edit, delete, or merge entries.
|
|||
|
|
|
|||
|
|
### FR-16
|
|||
|
|
|
|||
|
|
User can approve registry entry.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.8 Search
|
|||
|
|
|
|||
|
|
### FR-17
|
|||
|
|
|
|||
|
|
User can search using natural language.
|
|||
|
|
|
|||
|
|
### FR-18
|
|||
|
|
|
|||
|
|
System maps queries to abilities/capabilities.
|
|||
|
|
|
|||
|
|
### FR-19
|
|||
|
|
|
|||
|
|
Search results include:
|
|||
|
|
|
|||
|
|
* repository name
|
|||
|
|
* matching ability
|
|||
|
|
* matching capability
|
|||
|
|
* confidence
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.9 Inspection UI
|
|||
|
|
|
|||
|
|
### FR-20
|
|||
|
|
|
|||
|
|
User can view repository profile.
|
|||
|
|
|
|||
|
|
### FR-21
|
|||
|
|
|
|||
|
|
UI shows hierarchical structure:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
Ability → Capability → Feature → Code
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### FR-22
|
|||
|
|
|
|||
|
|
User can drill down to:
|
|||
|
|
|
|||
|
|
* feature details
|
|||
|
|
* code locations
|
|||
|
|
* evidence
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7.10 API Access
|
|||
|
|
|
|||
|
|
### FR-23
|
|||
|
|
|
|||
|
|
System exposes API endpoints for:
|
|||
|
|
|
|||
|
|
* search
|
|||
|
|
* repository retrieval
|
|||
|
|
* capability lookup
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 8. **Non-Functional Requirements**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8.1 Performance
|
|||
|
|
|
|||
|
|
* search results returned within < 2 seconds
|
|||
|
|
* repository analysis < 2 minutes for medium repos
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8.2 Scalability
|
|||
|
|
|
|||
|
|
* support 100–1,000 repositories (MVP)
|
|||
|
|
* architecture allows later horizontal scaling
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8.3 Usability
|
|||
|
|
|
|||
|
|
* repository can be registered in < 2 minutes
|
|||
|
|
* inspection view understandable within 1 minute
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8.4 Extensibility
|
|||
|
|
|
|||
|
|
* schema versioned
|
|||
|
|
* ability to extend capability model later
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8.5 Reliability
|
|||
|
|
|
|||
|
|
* analysis failures do not corrupt registry
|
|||
|
|
* partial results allowed
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 9. **Data Model (Simplified)**
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
Repository:
|
|||
|
|
id
|
|||
|
|
name
|
|||
|
|
url
|
|||
|
|
description
|
|||
|
|
metadata
|
|||
|
|
|
|||
|
|
Ability:
|
|||
|
|
id
|
|||
|
|
name
|
|||
|
|
description
|
|||
|
|
confidence
|
|||
|
|
|
|||
|
|
Capability:
|
|||
|
|
id
|
|||
|
|
name
|
|||
|
|
description
|
|||
|
|
inputs
|
|||
|
|
outputs
|
|||
|
|
ability_refs
|
|||
|
|
|
|||
|
|
Feature:
|
|||
|
|
id
|
|||
|
|
name
|
|||
|
|
type
|
|||
|
|
location
|
|||
|
|
capability_refs
|
|||
|
|
|
|||
|
|
Evidence:
|
|||
|
|
id
|
|||
|
|
type
|
|||
|
|
reference
|
|||
|
|
capability_refs
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 10. **User Experience**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10.1 Key Screens
|
|||
|
|
|
|||
|
|
### 1. Repository Registration
|
|||
|
|
|
|||
|
|
* input URL
|
|||
|
|
* confirm metadata
|
|||
|
|
|
|||
|
|
### 2. Analysis View
|
|||
|
|
|
|||
|
|
* detected structure
|
|||
|
|
* proposed abilities/capabilities/features
|
|||
|
|
|
|||
|
|
### 3. Review Interface
|
|||
|
|
|
|||
|
|
* edit/approve entries
|
|||
|
|
|
|||
|
|
### 4. Search Page
|
|||
|
|
|
|||
|
|
* natural language search
|
|||
|
|
* result list
|
|||
|
|
|
|||
|
|
### 5. Repository Profile Page
|
|||
|
|
|
|||
|
|
* ability map
|
|||
|
|
* drill-down navigation
|
|||
|
|
* code links
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 11. **Success Metrics**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11.1 Product Metrics
|
|||
|
|
|
|||
|
|
* time to understand a repository < 5 minutes
|
|||
|
|
* number of repositories indexed
|
|||
|
|
* number of successful searches
|
|||
|
|
* user engagement with inspection view
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11.2 Qualitative Metrics
|
|||
|
|
|
|||
|
|
* “I understand what this repo does now”
|
|||
|
|
* “I found something reusable”
|
|||
|
|
* “This saved me time”
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 12. **Risks**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12.1 Extraction Quality Risk
|
|||
|
|
|
|||
|
|
* automated inference may be inaccurate
|
|||
|
|
|
|||
|
|
**Mitigation:** human review required
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12.2 Over-Complexity Risk
|
|||
|
|
|
|||
|
|
* ontology becomes too heavy
|
|||
|
|
|
|||
|
|
**Mitigation:** keep schema minimal in v0.1
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 12.3 Adoption Risk
|
|||
|
|
|
|||
|
|
* users may not contribute metadata
|
|||
|
|
|
|||
|
|
**Mitigation:** provide value via auto-analysis first
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 13. **Future Extensions**
|
|||
|
|
|
|||
|
|
* integration with CI/CD for live updates
|
|||
|
|
* ability benchmarking integration (ties back to GIL)
|
|||
|
|
* capability maturity scoring
|
|||
|
|
* dependency graph across repositories
|
|||
|
|
* marketplace / discovery layer
|
|||
|
|
* automated code reasoning agents
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 14. **Positioning**
|
|||
|
|
|
|||
|
|
> The Repository Ability Registry is the missing orientation layer between raw code and practical reuse—making repositories understandable, comparable, and actionable.
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
xxx
|