coulomb/repo-scoping
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bee770fad77ba7efd075d89e5198741903c9d57a
repo-scoping/wiki/UseCaseCatalog.md

12 KiB
Raw Blame History

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

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:

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

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

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

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

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

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

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

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

/.well-known/repo-abilities.yaml

6. MVP Use Cases

For the first version, implement only these:

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

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

Reference in New Issue View Git Blame Copy Permalink