generated from coulomb/repo-seed
Add intent-scope gap analysis and REUSE-WP-0003 workplan
Document gaps between INTENT.md and SCOPE.md, refresh SCOPE with current MVP capabilities, and seed the follow-up workplan for documentation alignment, registry CLI tooling, and coverage growth.
This commit is contained in:
288
docs/IntentScopeGapAnalysis.md
Normal file
288
docs/IntentScopeGapAnalysis.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# INTENT ↔ SCOPE Gap Analysis
|
||||
|
||||
**Repository:** `reuse-surface`
|
||||
**Artifact:** `docs/IntentScopeGapAnalysis.md`
|
||||
**Status:** Living analysis
|
||||
**Created:** 2026-06-15
|
||||
**Purpose:** Record alignment, drift, and open gaps between declared intent and
|
||||
current delivered scope so future workplans can close them deliberately.
|
||||
|
||||
---
|
||||
|
||||
## 1. Summary
|
||||
|
||||
`INTENT.md` describes the long-term capability registry product: a reuse surface
|
||||
that makes capabilities visible, assessable, and consumable across planning and
|
||||
implementation. `SCOPE.md` describes what the repository actually delivers today:
|
||||
an MVP registry foundation at **A0 availability** with manual, Markdown-first
|
||||
workflows.
|
||||
|
||||
The two documents are **directionally aligned** on registry-first reuse, four
|
||||
maturity dimensions, and human/agent consumers. The main gaps are:
|
||||
|
||||
1. **Delivery depth** — INTENT promises eventual technical foundation and broad
|
||||
planning/implementation support; SCOPE delivers informational tooling only.
|
||||
2. **Structural drift** — INTENT's expected repository layout and entry shape
|
||||
differ from the implemented layout and schema in small but important ways.
|
||||
3. **Evidence and operations** — INTENT emphasizes consumer evidence and
|
||||
progress tracking; SCOPE has no reliability evidence, promotion history, or
|
||||
automated validation yet.
|
||||
4. **Document cross-coverage** — SCOPE operationalizes State Hub, MVP acceptance
|
||||
criteria, and helix_forge domain context that INTENT does not mention; INTENT
|
||||
carries success criteria and conceptual depth that SCOPE does not restate.
|
||||
|
||||
**Current reuse-surface vector (self-assessment):** `D4 / A0 / C3 / R0`
|
||||
|
||||
---
|
||||
|
||||
## 2. Alignment Matrix
|
||||
|
||||
| Topic | INTENT.md | SCOPE.md | Status |
|
||||
|---|---|---|---|
|
||||
| Registry-first boundary | Unregistered capabilities are invisible | Same | Aligned |
|
||||
| Four maturity dimensions | D, A, C, R with separate internal/external evidence | Same model in use | Aligned |
|
||||
| Human and agent consumers | Registry formats for both | Markdown + YAML index | Aligned |
|
||||
| Reuse over inventory | Explicit principle | Implicit in workflows | Aligned |
|
||||
| Planning vs implementation reuse | Distinct dimensions | Reflected in query guidance | Aligned |
|
||||
| No internal code quality as maturity | Out of scope | Out of scope | Aligned |
|
||||
| No hosting registered capabilities | Implied | Explicit out of scope | Aligned |
|
||||
| Target maturity vectors | Expected per capability | Supported in entry schema | Aligned |
|
||||
| Broken expectations as evidence | Guiding principle | Supported in schema/entries | Aligned |
|
||||
| Technical foundation | "Eventually technical" | A0 only, no CLI/API | Gap |
|
||||
| Success criteria | Eight outcomes listed | Partially met, not enumerated | Gap |
|
||||
| Repository layout | `standards/`, `docs/`, JSON schema | `specs/`, `docs/` missing, YAML schema | Drift |
|
||||
| State Hub / workplans | Not mentioned | In scope and current state | SCOPE-only |
|
||||
| MVP acceptance criteria | Not mentioned | Claimed satisfied manually | SCOPE-only |
|
||||
| Domain scope | Cross-repo/product/org | helix_forge sample registry | Narrower delivery |
|
||||
|
||||
---
|
||||
|
||||
## 3. INTENT → SCOPE Gaps
|
||||
|
||||
What INTENT declares that SCOPE does not yet deliver.
|
||||
|
||||
### 3.1 Technical foundation (High)
|
||||
|
||||
| INTENT claim | Current SCOPE reality | Gap |
|
||||
|---|---|---|
|
||||
| "Conceptual, structural, and **eventually technical** foundation" | Documentation-only repo, A0 availability | No CLI, validator, exporter, or API |
|
||||
| Implementation support through discoverable consumption modes | Manual index filtering only | No machine-assisted query or export |
|
||||
| Reference tooling | `tools/README.md` documents planned commands | Executable tools do not exist |
|
||||
|
||||
**Impact:** Implementation reuse still depends on humans/agents reading files.
|
||||
INTENT's "available enough to build with" mantra is only partially true for
|
||||
registry metadata itself.
|
||||
|
||||
**Suggested follow-up:** Workplan for CLI validate/query/export (PRD section 17).
|
||||
|
||||
### 3.2 Planning support breadth (Medium)
|
||||
|
||||
| INTENT claim | Current SCOPE reality | Gap |
|
||||
|---|---|---|
|
||||
| Planning support for prototype, MVP, enhancement, platform decisions | Manual compare/search guidance | No gap reports, roadmap views, or platformization filters |
|
||||
| Identify capability gaps, duplicates, overlaps, standardization candidates | Duplicate guidance only | No overlap detection, gap aggregation, or standardization workflow |
|
||||
| Track progress from named ideas to generalized capabilities | Promotion via front matter edits | No promotion history or changelog |
|
||||
|
||||
**Impact:** Planning reuse works for small registries; does not scale without
|
||||
tooling or disciplined manual process.
|
||||
|
||||
**Suggested follow-up:** Index views for "D5+/A0-A1" planning candidates and
|
||||
"D5+/A4+" implementation candidates; promotion history field or log.
|
||||
|
||||
### 3.3 Success criteria coverage (Medium)
|
||||
|
||||
INTENT success criteria vs current delivery:
|
||||
|
||||
| Success criterion | Met today? | Notes |
|
||||
|---|---|---|
|
||||
| Find reusable capabilities before rebuilding | Partial | Index + 3 samples; coverage is thin |
|
||||
| Compare maturity consistently | Yes | Vectors and schema enums |
|
||||
| Distinguish conceptual readiness from delivery | Yes | D vs A separation |
|
||||
| Distinguish internal assessment from external evidence | Yes | `maturity` vs `external_evidence` |
|
||||
| Plan prototype/MVP/enhancement/platform work | Partial | Guidance only, no reports |
|
||||
| Identify gaps, duplicates, overlaps, standardization candidates | Partial | Manual duplicate check only |
|
||||
| Track progress to generalized capabilities | No | No history or timeline |
|
||||
| Make reuse normal in product/architecture work | Partial | Agent instructions exist; tooling weak |
|
||||
|
||||
### 3.4 Expected repository layout (Low–Medium)
|
||||
|
||||
INTENT "Initial Repository Role" layout differs from delivered layout:
|
||||
|
||||
| INTENT path | Delivered path | Drift |
|
||||
|---|---|---|
|
||||
| `standards/CapabilityMaturityStandard.md` | `specs/CapabilityMaturityStandard.md` | Renamed directory |
|
||||
| `registry/capabilities.yaml` | `registry/capabilities/*.md` + `registry/indexes/capabilities.yaml` | Split canonical entries and index |
|
||||
| `registry/examples/` | `registry/capabilities/` (samples inline) | Different organization |
|
||||
| `schemas/capability.schema.json` | `schemas/capability.schema.yaml` | Format and location differ |
|
||||
| `docs/CapabilityRegistryConcept.md` | Missing | Not authored |
|
||||
| `docs/CapabilityAssessmentGuide.md` | Partially covered by `registry/README.md` | Concept guide missing |
|
||||
|
||||
**Impact:** New contributors reading INTENT first will look for paths that do
|
||||
not exist. SCOPE layout is authoritative for operations; INTENT layout is stale.
|
||||
|
||||
**Suggested follow-up:** Update INTENT "Initial Repository Role" to match
|
||||
delivered structure, or add redirect notes.
|
||||
|
||||
### 3.5 Registry entry shape drift (Low)
|
||||
|
||||
INTENT example uses:
|
||||
|
||||
```yaml
|
||||
external_evidence:
|
||||
completeness:
|
||||
current: C1
|
||||
reliability:
|
||||
current: R0
|
||||
```
|
||||
|
||||
Implemented schema and entries use `level` instead of `current` under
|
||||
`external_evidence`, matching `specs/CapabilityMaturityStandard.md` section 10.
|
||||
|
||||
**Impact:** Minor authoring confusion between INTENT and schema/template.
|
||||
|
||||
**Suggested follow-up:** Align INTENT example to `level` or document the alias.
|
||||
|
||||
### 3.6 Consumer reliability evidence (Medium)
|
||||
|
||||
INTENT requires reliability from bugs, tickets, incidents, ratings, adoption.
|
||||
SCOPE supports recording fields but:
|
||||
|
||||
- No sample entry has reliability above R0 except the feature-control example
|
||||
(R3 with thin evidence)
|
||||
- reuse-surface itself has **R0** — no consumer feedback loop for the registry
|
||||
|
||||
**Impact:** External evidence dimension is structurally present but weakly
|
||||
populated.
|
||||
|
||||
---
|
||||
|
||||
## 4. SCOPE → INTENT Gaps
|
||||
|
||||
What SCOPE asserts that INTENT does not declare.
|
||||
|
||||
### 4.1 Operational integration (Low)
|
||||
|
||||
SCOPE includes State Hub workplans, ADR-001 consistency sync, and session
|
||||
protocol. INTENT is product-conceptual and omits custodian workflow entirely.
|
||||
|
||||
**Assessment:** Not a product conflict. SCOPE correctly adds repository
|
||||
operations. INTENT may optionally reference workplan-driven evolution.
|
||||
|
||||
### 4.2 MVP framing (Low)
|
||||
|
||||
SCOPE maps deliverables to `specs/ProductRequirementsDocument.md` sections 15–16
|
||||
and claims MVP acceptance criteria are met manually. INTENT does not define MVP
|
||||
boundaries or acceptance tests.
|
||||
|
||||
**Assessment:** SCOPE is more precise about current phase. INTENT remains the
|
||||
north star; SCOPE is the phase boundary.
|
||||
|
||||
### 4.3 Domain anchoring (Low)
|
||||
|
||||
SCOPE inventories three **helix_forge** sample capabilities. INTENT describes
|
||||
cross-repo, product, and organizational reuse generically.
|
||||
|
||||
**Assessment:** Expected at MVP stage. INTENT target of D7 generalized primitives
|
||||
is not contradicted — sample scope is intentionally narrow.
|
||||
|
||||
### 4.4 Verification commands (Low)
|
||||
|
||||
SCOPE documents `rg --files`, `git diff --check`, and fix-consistency. INTENT
|
||||
has no verification or change-management guidance.
|
||||
|
||||
**Assessment:** SCOPE appropriately operationalizes delivery discipline.
|
||||
|
||||
---
|
||||
|
||||
## 5. Contradictions and Broken Expectations
|
||||
|
||||
Explicit mismatches a consumer might reasonably assume from reading both files:
|
||||
|
||||
| Expectation | Source | Reality | Severity |
|
||||
|---|---|---|---|
|
||||
| "Eventually technical foundation" is underway | INTENT scope section | No package, CLI, or API | Medium |
|
||||
| Maturity standard lives under `standards/` | INTENT layout | Lives under `specs/` | Low |
|
||||
| Single `capabilities.yaml` registry file | INTENT layout | Per-entry Markdown + separate index | Low |
|
||||
| JSON schema file exists | INTENT layout | YAML JSON Schema instead | Low |
|
||||
| Concept and assessment guides exist under `docs/` | INTENT layout | Only this gap analysis so far | Medium |
|
||||
| Registry can be searched by maturity automatically | INTENT success + SCOPE "possible now" | Manual index scan only | Medium |
|
||||
| Implementation reuse is supported | INTENT in-scope bullet | Only for entries with A2+ artifacts elsewhere | Medium |
|
||||
|
||||
No direct logical contradiction on registry-first boundary or maturity model
|
||||
separation was found.
|
||||
|
||||
---
|
||||
|
||||
## 6. Completeness Assessment (SCOPE vs INTENT)
|
||||
|
||||
Using INTENT's own completeness framing for the **reuse-surface product**:
|
||||
|
||||
| Area | INTENT expectation | Current SCOPE delivery | Level |
|
||||
|---|---|---|---|
|
||||
| Registry model and principles | Full | `INTENT.md` + `specs/` | C4 |
|
||||
| Maturity standard | Full | `specs/CapabilityMaturityStandard.md` | C5 |
|
||||
| Entry authoring | Full for MVP | Template + schema + README | C4 |
|
||||
| Sample registry | Examples expected | 3 helix_forge entries | C3 |
|
||||
| Discovery surface | Machine-readable | YAML index | C3 |
|
||||
| Validation | Implied tooling | Manual checklist | C2 |
|
||||
| Search/filter | Supported | Documented manual patterns | C2 |
|
||||
| Agent instructions | Expected | `AGENTS.md` registry section | C4 |
|
||||
| Technical consumption of registry | A3+ target natural for tools | A0 | C1 |
|
||||
| Consumer evidence for registry itself | Should be recorded | None (R0) | C1 |
|
||||
| Planning reports and gap analytics | Success criteria | Not present | C1 |
|
||||
| Documentation canon | Concept + assessment guides | Partial | C2 |
|
||||
|
||||
**Overall completeness vs INTENT:** **C3 (Functional Core)** — the central
|
||||
registry MVP works manually, but variants, tooling, evidence, and conceptual
|
||||
docs remain incomplete.
|
||||
|
||||
---
|
||||
|
||||
## 7. Reliability Assessment (SCOPE vs INTENT)
|
||||
|
||||
| Signal | State |
|
||||
|---|---|
|
||||
| Automated tests | None |
|
||||
| Schema validation in CI | None |
|
||||
| Consumer feedback on registry workflows | None |
|
||||
| Production or repeated agent usage evidence | None |
|
||||
| Known friction | Manual index maintenance; schema/INTENT field naming drift |
|
||||
|
||||
**Overall reliability vs INTENT consumer-evidence framing:** **R0 (Unknown)** for
|
||||
the registry product itself. Individual registered capabilities may carry their
|
||||
own evidence (e.g. feature-control at R3).
|
||||
|
||||
---
|
||||
|
||||
## 8. Priority Gap Closure Order
|
||||
|
||||
Recommended sequence for future workplans:
|
||||
|
||||
| Priority | Gap | Suggested outcome |
|
||||
|---|---|---|
|
||||
| 1 | INTENT layout stale | Update INTENT "Initial Repository Role" to match `SCOPE.md` layout |
|
||||
| 2 | No automated validation | CLI or script: validate entries against schema |
|
||||
| 3 | Thin registry coverage | Register additional helix_forge capabilities beyond 3 samples |
|
||||
| 4 | Missing concept docs | Add `docs/CapabilityRegistryConcept.md` distilled from INTENT |
|
||||
| 5 | No promotion history | Add `promotion_history` to schema or separate changelog |
|
||||
| 6 | Search/filter manual only | CLI `query` with discovery/availability filters |
|
||||
| 7 | No registry export | YAML/JSON bundle export for agents (UC-RS-019) |
|
||||
| 8 | Self-reliability evidence | Dogfood registry; record friction as reliability evidence |
|
||||
|
||||
---
|
||||
|
||||
## 9. Document Maintenance Rules
|
||||
|
||||
- Re-run this analysis when either `INTENT.md` or `SCOPE.md` changes materially.
|
||||
- When a gap closes, update section 3–5 and adjust the self-assessment vector.
|
||||
- New workplans that close gaps should reference the relevant row in section 8.
|
||||
- Prefer updating `SCOPE.md` for delivery truth and `INTENT.md` for product
|
||||
truth; use this file to track delta between them.
|
||||
|
||||
---
|
||||
|
||||
## 10. Change Log
|
||||
|
||||
| Date | Change |
|
||||
|---|---|
|
||||
| 2026-06-15 | Initial analysis after REUSE-WP-0002 completion |
|
||||
Reference in New Issue
Block a user