generated from coulomb/repo-seed
611 lines
12 KiB
Markdown
611 lines
12 KiB
Markdown
UseCaseCatalog
|
|
|
|
*Register, analyse and explore git repos*
|
|
|
|
# Use Case Catalog
|
|
|
|
## Repository Scoping
|
|
|
|
## 1. Scope
|
|
|
|
The **Repository Scoping** allows users to register Git repositories, analyze their contents, extract or maintain structured descriptions of their **abilities, capabilities, features, evidence, and implementation locations**, and make this information searchable through efficient interfaces and a web UI.
|
|
|
|
Core promise:
|
|
|
|
> Register a repository. Understand what it can do. Inspect the evidence. Find what is useful.
|
|
|
|
---
|
|
|
|
# 2. Primary Actors
|
|
|
|
## Repository Owner
|
|
|
|
Maintains a Git repository and wants it represented accurately in the registry.
|
|
|
|
## Registry Curator
|
|
|
|
Reviews, improves, corrects, and approves extracted ability/capability/feature metadata.
|
|
|
|
## Developer / Architect
|
|
|
|
Searches across registered repositories to find reusable functionality or understand system structure.
|
|
|
|
## Agent / Automation
|
|
|
|
Uses API/CLI access to query repositories, capabilities, evidence, and implementation locations.
|
|
|
|
## Viewer / Explorer
|
|
|
|
Uses the web UI to browse and inspect registered repositories.
|
|
|
|
---
|
|
|
|
# 3. Core Domain Objects
|
|
|
|
```text
|
|
Repository
|
|
Ability
|
|
Capability
|
|
Feature
|
|
Evidence
|
|
Analysis Run
|
|
Registry Entry
|
|
Inspection View
|
|
Search Query
|
|
```
|
|
|
|
---
|
|
|
|
# 4. Use Case Overview
|
|
|
|
| ID | Use Case | Primary Actor |
|
|
| ----- | --------------------------------- | ------------------------ |
|
|
| UC-01 | Register Git Repository | Repository Owner |
|
|
| UC-02 | Import Repository Metadata | System |
|
|
| UC-03 | Analyze Repository Structure | System |
|
|
| UC-04 | Extract Candidate Abilities | System / Agent |
|
|
| UC-05 | Extract Candidate Capabilities | System / Agent |
|
|
| UC-06 | Extract Candidate Features | System / Agent |
|
|
| UC-07 | Link Features to Code Locations | System |
|
|
| UC-08 | Attach Evidence to Capabilities | System / Curator |
|
|
| UC-09 | Review and Approve Analysis | Registry Curator |
|
|
| UC-10 | Search Repositories by Need | Developer / Architect |
|
|
| UC-11 | Inspect Repository Ability Map | Developer / Architect |
|
|
| UC-12 | Compare Repositories | Developer / Architect |
|
|
| UC-13 | Detect Capability Gaps | Architect / Agent |
|
|
| UC-14 | Expose Registry via API | Agent / Automation |
|
|
| UC-15 | Update Registry After Repo Change | System |
|
|
| UC-16 | Export Registry Entry | Repository Owner / Agent |
|
|
|
|
---
|
|
|
|
# 5. Detailed Use Cases
|
|
|
|
## UC-01 — Register Git Repository
|
|
|
|
### Goal
|
|
|
|
Add a Git repository to the registry.
|
|
|
|
### Primary Actor
|
|
|
|
Repository Owner
|
|
|
|
### Preconditions
|
|
|
|
The actor has a repository URL and access rights if the repo is private.
|
|
|
|
### Main Flow
|
|
|
|
1. Actor opens “Register Repository”.
|
|
2. Actor enters Git URL.
|
|
3. Actor provides optional metadata:
|
|
|
|
* name
|
|
* description
|
|
* owner
|
|
* domain tags
|
|
* visibility
|
|
4. System validates access.
|
|
5. System creates a repository record.
|
|
6. System queues initial analysis.
|
|
|
|
### Postconditions
|
|
|
|
Repository exists in the registry with status `registered`.
|
|
|
|
---
|
|
|
|
## UC-02 — Import Repository Metadata
|
|
|
|
### Goal
|
|
|
|
Collect basic metadata from the Git repository.
|
|
|
|
### Primary Actor
|
|
|
|
System
|
|
|
|
### Main Flow
|
|
|
|
1. System clones or accesses the repository.
|
|
2. System reads metadata files:
|
|
|
|
* README
|
|
* package manifests
|
|
* build files
|
|
* license
|
|
* docs
|
|
* existing registry metadata
|
|
3. System stores detected metadata.
|
|
4. System prepares repository for deeper analysis.
|
|
|
|
### Postconditions
|
|
|
|
Repository has initial metadata and source snapshot reference.
|
|
|
|
---
|
|
|
|
## UC-03 — Analyze Repository Structure
|
|
|
|
### Goal
|
|
|
|
Create a structural map of the repository.
|
|
|
|
### Primary Actor
|
|
|
|
System
|
|
|
|
### Main Flow
|
|
|
|
1. System detects language/frameworks.
|
|
2. System identifies major folders and modules.
|
|
3. System detects APIs, CLIs, services, tests, examples, docs.
|
|
4. System stores structural findings.
|
|
5. System generates a repository structure summary.
|
|
|
|
### Output
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
languages:
|
|
- Python
|
|
interfaces:
|
|
- REST API
|
|
- CLI
|
|
tests:
|
|
- pytest
|
|
documentation:
|
|
- README.md
|
|
- docs/
|
|
```
|
|
|
|
---
|
|
|
|
## UC-04 — Extract Candidate Abilities
|
|
|
|
### Goal
|
|
|
|
Infer high-level usefulness from the repository.
|
|
|
|
### Primary Actor
|
|
|
|
System / Agent
|
|
|
|
### Main Flow
|
|
|
|
1. System analyzes README, docs, examples, names, and tests.
|
|
2. System proposes candidate abilities.
|
|
3. Each ability receives:
|
|
|
|
* name
|
|
* description
|
|
* confidence
|
|
* supporting sources
|
|
4. Candidate abilities are shown for review.
|
|
|
|
### Example Output
|
|
|
|
```yaml
|
|
abilities:
|
|
- name: Business Email Routing
|
|
confidence: 0.82
|
|
rationale: README and examples describe routing inbound messages.
|
|
```
|
|
|
|
---
|
|
|
|
## UC-05 — Extract Candidate Capabilities
|
|
|
|
### Goal
|
|
|
|
Identify bounded behaviors the repository provides.
|
|
|
|
### Primary Actor
|
|
|
|
System / Agent
|
|
|
|
### Main Flow
|
|
|
|
1. System inspects APIs, modules, functions, tests, examples.
|
|
2. System proposes capabilities.
|
|
3. System links capabilities to abilities.
|
|
4. System records confidence and source evidence.
|
|
|
|
### Example
|
|
|
|
```yaml
|
|
capabilities:
|
|
- name: Email Intent Classification
|
|
ability_refs:
|
|
- Business Email Routing
|
|
inputs:
|
|
- email subject
|
|
- email body
|
|
outputs:
|
|
- intent category
|
|
- confidence
|
|
```
|
|
|
|
---
|
|
|
|
## UC-06 — Extract Candidate Features
|
|
|
|
### Goal
|
|
|
|
Identify concrete exposed or implemented features.
|
|
|
|
### Primary Actor
|
|
|
|
System / Agent
|
|
|
|
### Main Flow
|
|
|
|
1. System detects endpoints, commands, UI components, config options, public functions, modules.
|
|
2. System creates candidate feature entries.
|
|
3. System links features to capabilities.
|
|
4. System records implementation locations.
|
|
|
|
### Example
|
|
|
|
```yaml
|
|
features:
|
|
- name: Classify Email Endpoint
|
|
type: REST endpoint
|
|
location: src/api/routes/classify.py
|
|
capability_refs:
|
|
- Email Intent Classification
|
|
```
|
|
|
|
---
|
|
|
|
## UC-07 — Link Features to Code Locations
|
|
|
|
### Goal
|
|
|
|
Make registry entries inspectable down to source code.
|
|
|
|
### Primary Actor
|
|
|
|
System
|
|
|
|
### Main Flow
|
|
|
|
1. System identifies file paths and symbols.
|
|
2. System links registry entries to code locations.
|
|
3. UI exposes links from ability → capability → feature → source.
|
|
4. Actor can inspect relevant files without browsing the whole repo.
|
|
|
|
### Postconditions
|
|
|
|
Features and capabilities are traceable to implementation.
|
|
|
|
---
|
|
|
|
## UC-08 — Attach Evidence to Capabilities
|
|
|
|
### Goal
|
|
|
|
Support trust in capability claims.
|
|
|
|
### Primary Actor
|
|
|
|
System / Curator
|
|
|
|
### Main Flow
|
|
|
|
1. System detects tests, examples, benchmarks, demos, docs.
|
|
2. System proposes evidence links.
|
|
3. Curator confirms or edits evidence.
|
|
4. Evidence is attached to capabilities.
|
|
|
|
### Evidence Types
|
|
|
|
```text
|
|
unit test
|
|
integration test
|
|
example
|
|
demo
|
|
benchmark
|
|
documentation
|
|
production usage note
|
|
manual review
|
|
```
|
|
|
|
---
|
|
|
|
## UC-09 — Review and Approve Analysis
|
|
|
|
### Goal
|
|
|
|
Allow human correction before registry metadata becomes authoritative.
|
|
|
|
### Primary Actor
|
|
|
|
Registry Curator
|
|
|
|
### Main Flow
|
|
|
|
1. Curator opens analysis results.
|
|
2. Curator reviews proposed abilities, capabilities, features, and evidence.
|
|
3. Curator accepts, edits, rejects, or merges entries.
|
|
4. System saves approved registry entry.
|
|
5. Repository status changes to `indexed`.
|
|
|
|
### Postconditions
|
|
|
|
Repository has a reviewed registry profile.
|
|
|
|
---
|
|
|
|
## UC-10 — Search Repositories by Need
|
|
|
|
### Goal
|
|
|
|
Find repositories using everyday language.
|
|
|
|
### Primary Actor
|
|
|
|
Developer / Architect
|
|
|
|
### Main Flow
|
|
|
|
1. Actor enters a query such as:
|
|
|
|
> “I need something that can classify incoming customer emails.”
|
|
2. System maps query to possible abilities and capabilities.
|
|
3. System returns matching repositories.
|
|
4. Results show:
|
|
|
|
* matching ability
|
|
* matching capability
|
|
* confidence
|
|
* maturity
|
|
* evidence level
|
|
|
|
### Postconditions
|
|
|
|
Actor can identify candidate repositories without knowing their names.
|
|
|
|
---
|
|
|
|
## UC-11 — Inspect Repository Ability Map
|
|
|
|
### Goal
|
|
|
|
Understand what a repository is useful for.
|
|
|
|
### Primary Actor
|
|
|
|
Developer / Architect
|
|
|
|
### Main Flow
|
|
|
|
1. Actor opens repository profile.
|
|
2. UI displays:
|
|
|
|
* repository summary
|
|
* abilities
|
|
* capabilities
|
|
* features
|
|
* evidence
|
|
* code links
|
|
3. Actor drills down from high-level ability to implementation details.
|
|
|
|
### Key UI Concept
|
|
|
|
```text
|
|
Ability
|
|
→ Capability
|
|
→ Feature
|
|
→ Code Location
|
|
→ Evidence
|
|
```
|
|
|
|
---
|
|
|
|
## UC-12 — Compare Repositories
|
|
|
|
### Goal
|
|
|
|
Compare multiple repositories by abilities, capabilities, maturity, and evidence.
|
|
|
|
### Primary Actor
|
|
|
|
Developer / Architect
|
|
|
|
### Main Flow
|
|
|
|
1. Actor selects two or more repositories.
|
|
2. System shows comparison matrix.
|
|
3. Actor compares:
|
|
|
|
* overlapping abilities
|
|
* unique capabilities
|
|
* maturity
|
|
* evidence quality
|
|
* interfaces
|
|
4. Actor identifies best fit or complementarity.
|
|
|
|
---
|
|
|
|
## UC-13 — Detect Capability Gaps
|
|
|
|
### Goal
|
|
|
|
Identify missing, weak, or unsupported capabilities.
|
|
|
|
### Primary Actor
|
|
|
|
Architect / Agent
|
|
|
|
### Main Flow
|
|
|
|
1. Actor defines desired ability or target capability map.
|
|
2. System compares desired map with registered repositories.
|
|
3. System reports:
|
|
|
|
* missing capabilities
|
|
* weakly evidenced capabilities
|
|
* duplicate capabilities
|
|
* abandoned repositories
|
|
* features without mapped capability
|
|
4. Actor uses results for planning.
|
|
|
|
### Example Output
|
|
|
|
```text
|
|
Gap: Document classification ability exists, but no repository provides benchmarked German-language evaluation.
|
|
```
|
|
|
|
---
|
|
|
|
## UC-14 — Expose Registry via API
|
|
|
|
### Goal
|
|
|
|
Allow agents and external tools to query the registry.
|
|
|
|
### Primary Actor
|
|
|
|
Agent / Automation
|
|
|
|
### Main Flow
|
|
|
|
1. Agent calls registry API.
|
|
2. API supports queries such as:
|
|
|
|
* find repositories by ability
|
|
* show capability details
|
|
* list features of repo
|
|
* retrieve evidence links
|
|
3. API returns structured JSON.
|
|
|
|
### Example
|
|
|
|
```http
|
|
GET /api/capabilities?query=email-routing
|
|
```
|
|
|
|
---
|
|
|
|
## UC-15 — Update Registry After Repo Change
|
|
|
|
### Goal
|
|
|
|
Keep registry entries aligned with repository changes.
|
|
|
|
### Primary Actor
|
|
|
|
System
|
|
|
|
### Main Flow
|
|
|
|
1. System detects repository change.
|
|
2. System runs incremental analysis.
|
|
3. System compares old and new findings.
|
|
4. System flags changed abilities/capabilities/features.
|
|
5. Curator reviews differences.
|
|
6. Registry entry is updated.
|
|
|
|
### Postconditions
|
|
|
|
Registry reflects current repository state.
|
|
|
|
---
|
|
|
|
## UC-16 — Export Registry Entry
|
|
|
|
### Goal
|
|
|
|
Allow registry data to travel with the repository.
|
|
|
|
### Primary Actor
|
|
|
|
Repository Owner / Agent
|
|
|
|
### Main Flow
|
|
|
|
1. Actor requests export.
|
|
2. System generates `repo-abilities.yaml`.
|
|
3. Actor commits file into repository.
|
|
4. Future analyses can use it as a prior.
|
|
|
|
### Output
|
|
|
|
```text
|
|
/.well-known/repo-abilities.yaml
|
|
```
|
|
|
|
---
|
|
|
|
# 6. MVP Use Cases
|
|
|
|
For the first version, implement only these:
|
|
|
|
```text
|
|
UC-01 Register Git Repository
|
|
UC-02 Import Repository Metadata
|
|
UC-03 Analyze Repository Structure
|
|
UC-04 Extract Candidate Abilities
|
|
UC-05 Extract Candidate Capabilities
|
|
UC-06 Extract Candidate Features
|
|
UC-09 Review and Approve Analysis
|
|
UC-10 Search Repositories by Need
|
|
UC-11 Inspect Repository Ability Map
|
|
```
|
|
|
|
Everything else can follow.
|
|
|
|
---
|
|
|
|
# 7. Core MVP User Journey
|
|
|
|
```text
|
|
Register repo
|
|
↓
|
|
Analyze repo
|
|
↓
|
|
Review extracted ability/capability/feature map
|
|
↓
|
|
Publish registry profile
|
|
↓
|
|
Search and inspect repos through web UI/API
|
|
```
|
|
|
|
---
|
|
|
|
# 8. Product Principle
|
|
|
|
The registry should not merely answer:
|
|
|
|
> “What files are in this repository?”
|
|
|
|
It should answer:
|
|
|
|
> **“What can this repository help me do, how does it do it, and where can I inspect the proof?”**
|
|
|
|
|
|
xxx
|