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