generated from coulomb/repo-seed
496 lines
7.1 KiB
Markdown
496 lines
7.1 KiB
Markdown
ProductRequirementsSpecV0.1
|
||
|
||
*Repository Scoping Requirements*
|
||
|
||
# **Product Requirements Document (PRD)**
|
||
|
||
## **Repository Scoping (v0.1)**
|
||
|
||
---
|
||
|
||
# 1. **Purpose**
|
||
|
||
The **Repository Scoping** 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 Scoping is the missing orientation layer between raw code and practical reuse—making repositories understandable, comparable, and actionable.
|
||
|
||
|
||
|
||
|
||
xxx
|