gh-jschulte-claude-plugins-stackshift/skills/analyze/operations/completeness-assessment.md

# Completeness Assessment

Assess how complete the application implementation is.

## Overview

Estimate the percentage completion for:
- Overall application
- Backend implementation
- Frontend implementation
- Test coverage
- Documentation
- Deployment/Infrastructure

---

## Evidence Collection

### Placeholder Files

Look for files indicating incomplete work:

```bash
# Find TODO/WIP/PLACEHOLDER files
find . -iname "*todo*" -o -iname "*wip*" -o -iname "*placeholder*" -o -iname "*draft*" 2>/dev/null \
  | grep -v "node_modules\|\.git"

# Find empty or near-empty files
find . -type f -size 0 2>/dev/null | grep -v "node_modules\|\.git\|\.keep"

# Files with just placeholders
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null \
  | xargs grep -l "TODO\|FIXME\|PLACEHOLDER\|XXX\|HACK" \
  | head -20
```

### README Mentions

```bash
# Search README for incomplete features
grep -i "todo\|wip\|work in progress\|coming soon\|not yet\|planned\|roadmap\|incomplete" README.md 2>/dev/null
```

### Code Comments

```bash
# Count TODO/FIXME comments
grep -r "TODO\|FIXME\|XXX\|HACK" src/ 2>/dev/null | wc -l

# Show sample TODOs
grep -r "TODO\|FIXME" src/ 2>/dev/null | head -10
```

---

## Component-Specific Assessment

### Backend Completeness

**Check for:**

1. **API Endpoints**
   ```bash
   # Count API routes
   find . -path "*/api/*" -o -path "*/routes/*" 2>/dev/null | wc -l

   # Find routes with placeholder responses
   grep -r "res.json({})\|return {}\|NotImplementedError" src/api/ src/routes/ 2>/dev/null
   ```

2. **Business Logic**
   ```bash
   # Count service/controller files
   find . -path "*/services/*" -o -path "*/controllers/*" 2>/dev/null | wc -l

   # Find stub implementations
   grep -r "throw new Error.*not implemented\|NotImplementedError" src/ 2>/dev/null
   ```

3. **Database**
   ```bash
   # Check if migrations are applied
   ls -la prisma/migrations/ 2>/dev/null | wc -l

   # Check for empty seed files
   ls -la prisma/seed.ts 2>/dev/null
   ```

4. **Authentication**
   ```bash
   # Check for auth middleware
   find . -name "*auth*" -o -name "*session*" | grep -v node_modules

   # Look for JWT/session handling
   grep -r "jwt\|jsonwebtoken\|express-session\|passport" package.json src/ 2>/dev/null
   ```

**Estimate:**
- 100% = All endpoints implemented, tested, documented
- 75% = All endpoints exist, some missing tests/validation
- 50% = Core endpoints done, advanced features missing
- 25% = Skeleton only, most logic unimplemented
- 0% = No backend implementation

### Frontend Completeness

**Check for:**

1. **Pages/Views**
   ```bash
   # Count pages
   find . -path "*/pages/*" -o -path "*/app/*" -o -path "*/views/*" 2>/dev/null \
     | grep -E "\.(tsx?|jsx?|vue)$" | wc -l

   # Find placeholder pages
   grep -r "Coming Soon\|Under Construction\|TODO\|Placeholder" app/ pages/ components/ 2>/dev/null
   ```

2. **Components**
   ```bash
   # Count components
   find . -path "*/components/*" | grep -E "\.(tsx?|jsx?|vue)$" | wc -l

   # Find stub components
   grep -r "return null\|return <div>TODO\|placeholder" components/ 2>/dev/null
   ```

3. **Styling**
   ```bash
   # Check for styling setup
   ls -la tailwind.config.* 2>/dev/null
   find . -name "*.css" -o -name "*.scss" 2>/dev/null | head -10

   # Check if components are styled
   grep -r "className\|style=" components/ 2>/dev/null | wc -l
   ```

4. **State Management**
   ```bash
   # Check for state management
   grep -r "redux\|zustand\|recoil\|jotai\|mobx" package.json 2>/dev/null
   grep -r "createContext\|useContext" src/ app/ 2>/dev/null | wc -l
   ```

**Estimate:**
- 100% = All pages implemented, styled, interactive
- 75% = All pages exist, some missing polish/interactivity
- 50% = Core pages done, advanced features missing
- 25% = Skeleton pages, minimal styling/functionality
- 0% = No frontend implementation

### Testing Completeness

**Check for:**

1. **Test Files**
   ```bash
   # Count test files
   find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | wc -l

   # Count tests
   grep -r "test(\|it(\|describe(" tests/ __tests__/ src/ 2>/dev/null | wc -l
   ```

2. **Test Coverage**
   ```bash
   # Check for coverage reports
   ls -la coverage/ 2>/dev/null

   # Check test configuration
   ls -la jest.config.* vitest.config.* 2>/dev/null
   ```

3. **Test Types**
   ```bash
   # Unit tests
   find . -path "*/tests/unit/*" -o -name "*.unit.test.*" 2>/dev/null | wc -l

   # Integration tests
   find . -path "*/tests/integration/*" -o -name "*.integration.test.*" 2>/dev/null | wc -l

   # E2E tests
   find . -path "*/tests/e2e/*" -o -name "*.e2e.*" -o -name "cypress/" -o -name "playwright/" 2>/dev/null
   ```

**Estimate:**
- 100% = >80% code coverage, unit + integration + E2E tests
- 75% = 60-80% coverage, unit + integration tests
- 50% = 40-60% coverage, mostly unit tests
- 25% = <40% coverage, sparse unit tests
- 0% = No tests

### Documentation Completeness

Use findings from [documentation-scan.md](documentation-scan.md):

**Estimate:**
- 100% = README, API docs, architecture, deployment, developer guide, all current
- 75% = README + API docs + some architecture/deployment docs
- 50% = Good README, partial API docs
- 25% = Basic README only
- 0% = No meaningful documentation

### Infrastructure/Deployment Completeness

**Check for:**

1. **Infrastructure as Code**
   ```bash
   # Check for IaC files
   find . -name "*.tf" -o -name "serverless.yml" -o -name "cdk.json" 2>/dev/null

   # Count resources defined
   grep -r "resource\|AWS::" infrastructure/ terraform/ 2>/dev/null | wc -l
   ```

2. **CI/CD**
   ```bash
   # GitHub Actions
   ls -la .github/workflows/ 2>/dev/null

   # Other CI/CD
   ls -la .gitlab-ci.yml .circleci/config.yml .travis.yml 2>/dev/null
   ```

3. **Environment Configuration**
   ```bash
   # Environment files
   ls -la .env.example .env.template 2>/dev/null

   # Environment validation
   grep -r "dotenv\|env-var\|envalid" package.json src/ 2>/dev/null
   ```

4. **Deployment Scripts**
   ```bash
   # Deployment scripts
   find . -name "deploy.sh" -o -name "deploy.js" -o -name "deploy.ts" 2>/dev/null

   # Package scripts
   grep "deploy\|build\|start\|test" package.json 2>/dev/null
   ```

**Estimate:**
- 100% = Full IaC, CI/CD, monitoring, auto-deployment
- 75% = IaC + CI/CD, manual deployment
- 50% = Basic CI/CD, no IaC
- 25% = Manual deployment only
- 0% = No deployment setup

---

## Overall Completeness Calculation

Calculate weighted average:

```
Overall = (Backend × 0.3) + (Frontend × 0.3) + (Tests × 0.2) + (Docs × 0.1) + (Infra × 0.1)
```

Example:
- Backend: 100%
- Frontend: 60%
- Tests: 30%
- Docs: 40%
- Infra: 80%

Overall = (100 × 0.3) + (60 × 0.3) + (30 × 0.2) + (40 × 0.1) + (80 × 0.1)
        = 30 + 18 + 6 + 4 + 8
        = **66%**

---

## Missing Components Identification

List what's missing or incomplete:

**High Priority:**
- [ ] Frontend: User profile page (placeholder only)
- [ ] Frontend: Analytics dashboard (not started)
- [ ] Backend: Email notification service (stub)
- [ ] Tests: Integration tests for API (0 tests)
- [ ] Docs: API specification (no OpenAPI)

**Medium Priority:**
- [ ] Frontend: Mobile responsive design (partially done)
- [ ] Backend: Rate limiting (not implemented)
- [ ] Tests: E2E tests (no framework setup)
- [ ] Infra: Monitoring/alerting (not configured)

**Low Priority:**
- [ ] Frontend: Dark mode (placeholder toggle)
- [ ] Backend: Admin panel API (not started)
- [ ] Docs: Troubleshooting guide (missing)

---

## Evidence Summary

Document the evidence used for estimates:

```markdown
### Evidence

**Backend (100%):**
- 17 Lambda functions fully implemented
- All database models defined and migrated
- Authentication and authorization complete
- API endpoints tested and documented

**Frontend (60%):**
- 8 of 12 planned pages implemented
- Core components complete (Header, Footer, Nav)
- 4 pages are placeholder/TODO:
  - Analytics Dashboard (TODO comment in code)
  - User Settings (returns "Coming Soon")
  - Admin Panel (not started)
  - Reports (skeleton only)
- Styling ~80% complete

**Tests (30%):**
- 12 unit tests for backend utilities
- 0 integration tests
- 0 E2E tests
- No test coverage reports
- jest.config.js exists but minimal tests

**Documentation (40%):**
- Good README with setup instructions
- No API documentation (no OpenAPI spec)
- No architecture diagrams
- Basic deployment guide
- No developer guide

**Infrastructure (80%):**
- Full Terraform IaC for AWS
- GitHub Actions CI/CD configured
- Auto-deploy to staging
- Manual production deploy
- No monitoring/alerting setup
```

---

## Output Format

```markdown
## Completeness Assessment

### Estimated Completion
- **Overall:** ~66%
- **Backend:** ~100%
- **Frontend:** ~60%
- **Tests:** ~30%
- **Documentation:** ~40%
- **Infrastructure:** ~80%

### Evidence
[Detailed evidence as shown above]

### Missing Components
[Categorized list of missing/incomplete features]

### Placeholder Files
- app/analytics/page.tsx (TODO comment)
- app/settings/page.tsx ("Coming Soon" text)
- src/services/email.ts (stub functions)

### TODO Comments
- Found 23 TODO/FIXME comments across codebase
- Most common: Frontend polish, missing tests, error handling
```

---

## Notes

- Be conservative with estimates - round down when uncertain
- Provide evidence for all estimates
- Consider quality, not just quantity (a poorly implemented feature counts less)
- Differentiate between "not started" vs "partially done" vs "mostly complete"