analyze

Gap Analysis Workflow

Analyze the project state, find documentation gaps, and assess completeness.

Context

You must load the following skills and read the following files before proceeding.

Skills

• katachi:framework-core - Workflow principles

Project state

• docs/planning/VISION.md - Project vision

Feature documentation

• docs/feature-specs/README.md - Feature capability index
• docs/feature-designs/README.md - Feature design index
• Read all feature-specs/ and feature-designs/ for completeness analysis

Decision indexes

• docs/architecture/README.md - Architecture decisions (ADRs)
• docs/design/README.md - Design patterns (DES)

Process

1. Read Current State

Read all documentation:

• Vision document
• Feature specs index (README.md)
• Feature designs index (README.md)
• All feature-specs/ documents and domain READMEs
• All feature-designs/ documents and domain READMEs
• All ADRs and DES

2. Check Feature Documentation Completeness

For each capability domain:

• Does it have a README.md index?
• Are all sub-capabilities documented?
• Do sub-capabilities have both specs AND designs?
• Are related decisions referenced?

For the feature specs structure:

• Is docs/feature-specs/README.md present and complete?
• Are all domains listed in the top-level index?
• Do domain READMEs list all sub-capabilities?
• Are sub-capability descriptions accurate?

For the feature designs structure:

• Is docs/feature-designs/README.md present and complete?
• Does it mirror the specs structure?
• Are design docs paired with spec docs?
• Are design decisions documented?

Generate gap report:

## Feature Documentation Gaps

### Missing Domain READMEs
- auth/: No README.md to index sub-capabilities
- payments/: No README.md to index sub-capabilities

### Missing Feature Specs
- api/users.md: Referenced in design but no spec exists
- reporting/analytics.md: Mentioned in vision but not documented

### Missing Feature Designs
- auth/login.md: Has spec but no design document
- api/endpoints.md: Has spec but no design rationale

### Incomplete Domain READMEs
- auth/README.md: Missing sub-capability "password-reset"
- projects/README.md: Sub-capability statuses not updated

### Missing Top-Level Indexes
- feature-specs/README.md: Not present (need to create)
- feature-designs/README.md: Not present (need to create)

### Orphaned Documents
- feature-designs/old-auth.md: Not referenced in any README

3. Check Decision Coverage

Look for undocumented decisions:

• Code patterns that aren't in DES
• Technology choices without ADRs
• Conventions followed but not documented
• Feature specs/designs missing decision references

## Potential Undocumented Decisions

### Technology Choices
- Using [library X] for [purpose] - no ADR exists
- Chose [approach Y] for [problem] - no ADR exists

### Patterns
- [Pattern Z] used in multiple features - no DES exists
- [Convention] followed across designs - should be DES

### Missing Decision References
- auth/login.md design doesn't reference ADR for token storage
- api/endpoints.md design doesn't reference DES for error handling

4. Check Cross-Reference Integrity

Verify references between documents:

• Do feature designs reference relevant ADRs?
• Do domain READMEs list all sub-capabilities?
• Are capability domains listed in top-level README?
• Are decision indexes up to date?

## Cross-Reference Issues

### Broken References
- payments/refund.md references ADR-012 which doesn't exist
- auth/README.md lists "mfa.md" which doesn't exist

### Missing References
- api/users.md design should reference ADR-005 (database choice)
- reporting/analytics.md should reference DES-003 (query patterns)

5. Check Vision Alignment

Compare documented features with vision:

• Are all workflows covered by features?
• Are core requirements addressed?
• Are features aligned with project goals?

## Vision Alignment

### Workflows
- [x] Workflow 1: Covered by auth/ and api/ features
- [ ] Workflow 2: No features documented yet
- [x] Workflow 3: Covered by reporting/ features

### Core Requirements
- [x] Requirement A: Addressed by auth/login.md, auth/oauth.md
- [ ] Requirement B: Not yet documented
- [x] Requirement C: Addressed by api/ features

### Out of Scope
- Feature X appears to be out of v1 scope - should it be removed?

6. Present Analysis

Show comprehensive report to user.

Organize by severity:

1. Critical: Missing core feature documentation, broken structure
2. Important: Incomplete domains, missing decisions
3. Minor: Documentation improvements, style consistency

7. Offer Next Steps

Based on gaps found:

"Based on this analysis, I recommend:

1. Create missing feature docs: api/users.md (spec + design)
2. Create domain READMEs: auth/README.md, payments/README.md
3. Document decision for [library X] as ADR
4. Extract [pattern Z] into DES
5. Fix broken reference: payments/refund.md → ADR-012

Which would you like to address first?"

Workflow

This is an analytical process:

• Read all documentation
• Check completeness
• Check decision coverage
• Check dependencies
• Check vision alignment
• Present findings
• Offer next steps