universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/skills/project-discovery/guide.md

@@ -0,0 +1,367 @@
+---
+scope: universal
+description: |
+  Assess project health, architecture, and risks before adding new features.
+  Use when: onboarding to legacy projects, starting new features on existing codebases, evaluating technical debt.
+  Keywords: discovery, assessment, audit, legacy, health check, technical debt, 現況評估, 風險分析, 技術債, 專案盤點.
+---
+
+# Project Discovery Guide
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/project-discovery/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-02-09
+**Applicability**: All AI coding assistants
+
+> **Utility Skill**: This skill combines existing UDS core standards into a structured discovery workflow. No dedicated core standard is required.
+
+---
+
+## Purpose
+
+Before adding new features to an existing codebase, you need a clear picture of its current state. Phase 0 — Discovery — provides a systematic assessment of code health, architecture, documentation, dependencies, and risk so you can plan changes with confidence.
+
+This skill guides you through 6 assessment steps, each referencing existing UDS standards for methodology and quality gates.
+
+## Quick Reference
+
+### Phase 0 Discovery Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                  Phase 0: Project Discovery                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  0.1  Code Health Check                                         │
+│       └─ Test coverage, lint issues, code smells                │
+│                                                                  │
+│  0.2  Architecture Understanding                                │
+│       └─ Entry points, module map, patterns                     │
+│                                                                  │
+│  0.3  Documentation Inventory                                   │
+│       └─ READMEs, ADRs, changelogs, inline docs                │
+│                                                                  │
+│  0.4  Code Review Snapshot                                      │
+│       └─ Sample audit of critical paths                         │
+│                                                                  │
+│  0.5  Dependency & Security Check                               │
+│       └─ Outdated packages, known vulnerabilities               │
+│                                                                  │
+│  0.6  Impact Scope Analysis                                     │
+│       └─ Change propagation, risk matrix                        │
+│                                                                  │
+│  ──────────────────────────────────────────────────────────────  │
+│  Output: Discovery Report (go / no-go / conditional)            │
+│  Next:  /reverse → /sdd → implement                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Step Summary
+
+| Step | Focus | Key Output | UDS Standards Referenced |
+|------|-------|------------|------------------------|
+| 0.1 | Code Health | Test coverage %, lint score, code smell count | Testing, Reverse Engineering |
+| 0.2 | Architecture | Module dependency diagram, pattern identification | AI-Friendly Architecture, Reverse Engineering |
+| 0.3 | Documentation | Doc coverage matrix, staleness indicators | Documentation Structure, Changelog |
+| 0.4 | Code Review | Critical path audit, quality snapshot | Anti-Hallucination, Code Review Checklist |
+| 0.5 | Dependencies | Vulnerability report, outdated package list | Security, Check-in Standards |
+| 0.6 | Impact Scope | Risk matrix, change propagation map | Requirement Engineering |
+
+## Workflow Steps
+
+### Step 0.1: Code Health Check
+
+**Goal**: Establish a baseline measurement of code quality.
+
+**Actions**:
+1. Run existing test suite and record pass rate and coverage
+2. Run linter and count warnings/errors
+3. Identify code smells (long functions, deep nesting, duplicated logic)
+4. Check for dead code and unused exports
+
+**Output Format**:
+```markdown
+## Code Health Summary
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Test pass rate | 85/100 (85%) | ⚠️ Below target |
+| Test coverage | 42% | ❌ Low |
+| Lint errors | 23 | ⚠️ Needs attention |
+| Code smells | 7 major | ⚠️ Needs attention |
+```
+
+**Quality Gate**: If test pass rate < 70%, flag as high-risk before proceeding.
+
+**Referenced Standards**:
+- [Testing Standards](../../core/testing-standards.md)
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md)
+
+### Step 0.2: Architecture Understanding
+
+**Goal**: Map the system structure and identify architectural patterns.
+
+**Actions**:
+1. Identify entry points (main files, API routes, event handlers)
+2. Map module/package dependencies
+3. Identify architectural pattern (MVC, DDD, microservices, monolith, etc.)
+4. Note any anti-patterns (circular dependencies, god modules)
+5. Assess AI-friendliness (clear boundaries, discoverable structure)
+
+**Output Format**:
+```markdown
+## Architecture Overview
+
+**Pattern**: [Confirmed] MVC with service layer
+**Entry Points**: src/index.ts, src/api/routes.ts
+**Module Count**: 24 modules across 6 packages
+
+### Dependency Map (simplified)
+routes → controllers → services → repositories → database
+
+### Concerns
+- [Confirmed] Circular dependency between UserService ↔ AuthService
+- [Inferred] Tight coupling in payment module
+```
+
+**Quality Gate**: If no clear module boundaries exist, recommend architectural refactoring before feature work.
+
+**Referenced Standards**:
+- [AI-Friendly Architecture](../../core/ai-friendly-architecture.md)
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md)
+
+### Step 0.3: Documentation Inventory
+
+**Goal**: Assess documentation completeness and freshness.
+
+**Actions**:
+1. Check for README, CONTRIBUTING, CHANGELOG
+2. Scan for architecture decision records (ADRs)
+3. Evaluate inline documentation (JSDoc, docstrings, comments)
+4. Check if docs match current code state
+
+**Output Format**:
+```markdown
+## Documentation Inventory
+
+| Document | Exists | Last Updated | Current |
+|----------|--------|-------------|---------|
+| README.md | ✅ | 2025-06-15 | ⚠️ Stale |
+| CHANGELOG.md | ❌ | — | — |
+| API docs | ✅ | 2025-09-01 | ✅ Current |
+| ADRs | ❌ | — | — |
+| Inline docs | ⚠️ Partial | — | — |
+```
+
+**Quality Gate**: If README is missing or severely outdated, recommend documentation update as prerequisite.
+
+**Referenced Standards**:
+- [Documentation Structure](../../core/documentation-structure.md)
+- [Changelog Standards](../../core/changelog-standards.md)
+
+### Step 0.4: Code Review Snapshot
+
+**Goal**: Sample-audit critical code paths for quality and correctness.
+
+**Actions**:
+1. Identify the 3-5 most critical code paths (auth, payment, data access, etc.)
+2. Review each path using the Code Review Checklist
+3. Apply Anti-Hallucination labels — only report what you have actually read
+4. Note any security concerns or error handling gaps
+
+**Output Format**:
+```markdown
+## Code Review Snapshot
+
+### Critical Path: Authentication
+[Confirmed] Reviewed src/auth/login.ts, src/auth/middleware.ts
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Error handling | ⚠️ | Missing catch for token refresh failure |
+| Security | ✅ | bcrypt hashing, parameterized queries |
+| Readability | ✅ | Clear naming, reasonable function length |
+
+[Unknown] Token rotation policy — requires stakeholder input
+```
+
+**Quality Gate**: Any ❌ security finding requires immediate attention before feature work.
+
+**Referenced Standards**:
+- [Anti-Hallucination Guidelines](../../core/anti-hallucination.md)
+- [Code Review Checklist](../../core/code-review-checklist.md)
+
+### Step 0.5: Dependency & Security Check
+
+**Goal**: Identify vulnerable, outdated, or unnecessary dependencies.
+
+**Actions**:
+1. Run `npm audit` / `pip audit` / equivalent for the project's ecosystem
+2. List outdated packages with severity levels
+3. Check for known CVEs in dependencies
+4. Identify unused dependencies
+
+**Output Format**:
+```markdown
+## Dependency Report
+
+| Category | Count | Severity |
+|----------|-------|----------|
+| Critical vulnerabilities | 1 | ❌ High |
+| High vulnerabilities | 3 | ⚠️ Medium |
+| Outdated (major) | 5 | ⚠️ |
+| Outdated (minor/patch) | 12 | ℹ️ |
+| Unused dependencies | 2 | ℹ️ |
+```
+
+**Quality Gate**: Any critical vulnerability must be patched before adding new features.
+
+**Referenced Standards**:
+- [Security Standards](../../core/security-standards.md)
+- [Check-in Standards](../../core/checkin-standards.md)
+
+### Step 0.6: Impact Scope Analysis
+
+**Goal**: Map how proposed changes would propagate through the system.
+
+**Actions**:
+1. Identify the feature area(s) to be modified
+2. Trace direct and transitive dependencies
+3. Assess blast radius (how many modules touched)
+4. Build a risk matrix (likelihood vs. impact)
+
+**Output Format**:
+```markdown
+## Impact Analysis
+
+### Change Target: User profile module
+
+**Blast Radius**: 6 modules directly affected, 3 transitively
+
+### Risk Matrix
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Break auth flow | Medium | High | Add integration tests |
+| Payment regression | Low | Critical | Manual QA before deploy |
+| API contract change | High | Medium | Version API endpoint |
+```
+
+**Quality Gate**: If blast radius exceeds 30% of total modules, recommend incremental approach.
+
+**Referenced Standards**:
+- [Requirement Engineering](../../core/requirement-engineering.md)
+
+## Discovery Report Template
+
+After completing all 6 steps, synthesize findings into a Discovery Report:
+
+```markdown
+# Discovery Report: [Project Name]
+
+**Date**: YYYY-MM-DD
+**Assessed by**: [AI / Human]
+
+## Executive Summary
+[1-2 sentences: overall project health and readiness]
+
+## Verdict: [GO / NO-GO / CONDITIONAL]
+
+## Key Findings
+1. ...
+2. ...
+3. ...
+
+## Blockers (if any)
+- ...
+
+## Recommendations
+1. ...
+2. ...
+
+## Next Steps
+- [ ] /reverse (if legacy code needs SDD specs)
+- [ ] /sdd (for new feature specification)
+- [ ] Address blockers listed above
+```
+
+## Integration with Other Skills
+
+### With /reverse (Reverse Engineering)
+
+Use `/reverse` after discovery when:
+- Architecture is poorly documented
+- You need formal SDD specs for existing modules
+- Legacy code needs structured analysis before changes
+
+### With /sdd (Spec-Driven Development)
+
+Use `/sdd` after discovery to:
+- Write specifications for new features informed by discovery findings
+- Reference the Discovery Report for risk assessment sections
+
+### With /review (Code Review)
+
+The Step 0.4 snapshot is a lightweight version of `/review`. Use full `/review` when:
+- Discovery finds significant quality concerns
+- A deeper audit is needed before planning changes
+
+## Anti-Patterns to Avoid
+
+### What NOT to Do
+
+1. **Skipping Discovery**
+   - Wrong: Jump straight into coding on an unfamiliar codebase
+   - Right: Run `/discover` first to understand what you're working with
+
+2. **Fabricating Metrics**
+   - Wrong: "Test coverage is probably around 60%"
+   - Right: "[Unknown] Test coverage — need to run test suite to measure"
+
+3. **Incomplete Assessment**
+   - Wrong: Only check code health, skip dependencies
+   - Right: Complete all 6 steps for a reliable picture
+
+4. **Ignoring Quality Gates**
+   - Wrong: Proceed despite critical vulnerabilities
+   - Right: Address blockers before adding complexity
+
+## Best Practices
+
+- Read all relevant code before making claims (Anti-Hallucination)
+- Use certainty labels: `[Confirmed]`, `[Inferred]`, `[Unknown]`
+- Include source citations with file:line references
+- Clearly separate facts from recommendations
+- Tailor depth to project size (small project = lighter assessment)
+
+---
+
+## Related Standards
+
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md) — Deep code analysis methodology
+- [Testing Standards](../../core/testing-standards.md) — Test coverage benchmarks
+- [Security Standards](../../core/security-standards.md) — Vulnerability assessment
+- [AI-Friendly Architecture](../../core/ai-friendly-architecture.md) — Architecture assessment criteria
+- [Documentation Structure](../../core/documentation-structure.md) — Documentation completeness
+- [Changelog Standards](../../core/changelog-standards.md) — Change tracking
+- [Anti-Hallucination Guidelines](../../core/anti-hallucination.md) — Evidence-based analysis
+- [Code Review Checklist](../../core/code-review-checklist.md) — Review methodology
+- [Check-in Standards](../../core/checkin-standards.md) — Quality gates
+- [Requirement Engineering](../../core/requirement-engineering.md) — Impact analysis
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-02-09 | Initial release |
+
+---
+
+## License
+
+This skill is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)