gh-lerianstudio-ring-pm-team/skills/pre-dev-dependency-map/SKILL.md

name, description, trigger, skip_when, sequence

name	description	trigger	skip_when	sequence
pre-dev-dependency-map	Gate 6: Technology choices document - explicit, versioned, validated technology selections with justifications. Large Track only.	- Data Model passed Gate 5 validation - About to select specific technologies - Tempted to write "@latest" or "newest version" - Large Track workflow (2+ day features)	- Small Track workflow → skip to Task Breakdown - Technologies already locked → skip to Task Breakdown - Data Model not validated → complete Gate 5 first	after before pre-dev-data-model pre-dev-task-breakdown

Dependency Map - Explicit Technology Choices

Foundational Principle

Every technology choice must be explicit, versioned, validated, and justified.

Using vague or "latest" dependencies creates:

• Unreproducible builds across environments
• Hidden incompatibilities discovered during implementation
• Security vulnerabilities from unvetted versions
• Upgrade nightmares from undocumented constraints

The Dependency Map answers: WHAT specific products, versions, packages, and infrastructure we'll use. The Dependency Map never answers: HOW to implement features (that's Tasks/Subtasks).

When to Use This Skill

Use this skill when:

• Data Model has passed Gate 5 validation
• API Design has passed Gate 4 validation
• TRD has passed Gate 3 validation
• About to select specific technologies
• Tempted to write "@latest" or "newest version"
• Asked to finalize the tech stack
• Before breaking down implementation tasks

Mandatory Workflow

Phase 1: Technology Evaluation (Inputs Required)

1. Approved Data Model (Gate 5 passed) - data structures defined
2. Approved API Design (Gate 4 passed) - contracts specified
3. Approved TRD (Gate 3 passed) - architecture patterns locked
4. Map each TRD component to specific technology candidates
5. Map Data Model entities to storage technologies
6. Map API contracts to protocol implementations
7. Check team expertise for proposed technologies
8. Estimate costs for infrastructure and services

Phase 2: Stack Selection

For each technology choice:

1. Specify exact version (not "latest", not range unless justified)
2. List alternatives considered with trade-offs
3. Verify compatibility with other dependencies
4. Check security for known vulnerabilities
5. Validate licenses for compliance
6. Calculate costs (infrastructure + services + support)

Phase 3: Gate 6 Validation

MANDATORY CHECKPOINT - Must pass before proceeding to Task Breakdown:

• All dependencies have explicit versions
• No version conflicts exist
• No critical security vulnerabilities
• All licenses are compliant
• Team has expertise or learning path
• Costs are acceptable and documented
• Compatibility matrix verified
• All TRD components have dependencies mapped
• All API contracts have protocol implementations selected
• All Data Model entities have storage technologies selected

Explicit Rules

✅ DO Include in Dependency Map

• Exact package names with explicit versions (go.uber.org/zap@v1.27.0)
• Technology stack with version constraints (Go 1.24+, PostgreSQL 16)
• Infrastructure services with specifications (Valkey 8, MinIO latest-stable)
• External service SDKs with versions
• Development tool requirements (Go 1.24+, Docker 24+)
• Security dependencies (crypto libraries, scanners)
• Monitoring/observability tools (specific products)
• Compatibility matrices (package A requires package B >= X)
• License summary for all dependencies
• Cost analysis (infrastructure + services)

❌ NEVER Include in Dependency Map

• Implementation code or examples
• How to use the dependencies
• Task breakdown or work units
• Step-by-step setup instructions (those go in subtasks)
• Architectural patterns (those were in TRD)
• Business requirements (those were in PRD)

Version Specification Rules

1. Explicit versions: @v1.27.0 not @latest or ^1.0.0
2. Justified ranges: If using >=, document why (e.g., security patches)
3. Lock file referenced: go.mod, package-lock.json, etc.
4. Upgrade constraints: Document why version is locked/capped
5. Compatibility: Document known conflicts or requirements

Rationalization Table

Excuse	Reality
"Latest version is always best"	Latest is untested in your context. Pick specific, validate.
"I'll use flexible version ranges"	Ranges cause non-reproducible builds. Lock versions.
"Version numbers don't matter much"	They matter critically. Specify or face build failures.
"We can update versions later"	Document constraints now. Future you needs context.
"The team knows the stack already"	Document it anyway. Teams change, memories fade.
"Security scanning can happen in CI"	Security analysis must happen before committing. Do it now.
"We'll figure out costs in production"	Costs must be estimated before building. Calculate now.
"Compatibility issues will surface in tests"	Validate compatibility NOW. Don't wait for failures.
"License compliance is legal's problem"	You're responsible for your dependencies. Check licenses.
"I'll just use what the project template has"	Templates may be outdated/insecure. Validate explicitly.

Red Flags - STOP

If you catch yourself writing any of these in a Dependency Map, STOP:

• Version placeholders: @latest, @next, ^X.Y.Z without justification
• Vague descriptions: "latest stable", "current version", "newest"
• Missing version numbers: Just package names without versions
• Unchecked compatibility: Not verifying version conflicts
• Unvetted security: Not checking vulnerability databases
• Unknown licenses: Not documenting license types
• Estimated costs as "TBD" or "unknown"
• "We'll use whatever is default" (no default without analysis)

When you catch yourself: Stop and specify the exact version after proper analysis.

Gate 6 Validation Checklist

Before proceeding to Task Breakdown, verify:

Compatibility:

• All dependencies have explicit versions documented
• Version compatibility matrix is complete
• No known conflicts between dependencies
• Runtime requirements specified (OS, hardware)
• Upgrade path exists and is documented

Security:

• All dependencies scanned for vulnerabilities
• No critical (9.0+) or high (7.0-8.9) CVEs present
• Security update policy documented
• Supply chain verified (official sources only)

Feasibility:

• Team has expertise or documented learning path
• All tools are available/accessible
• Licensing allows commercial use
• Costs fit within budget

Completeness:

• Every TRD component has dependencies mapped
• Development environment fully specified
• CI/CD dependencies documented
• Monitoring/observability stack complete

Documentation:

• License summary created
• Cost analysis completed with estimates
• Known constraints documented
• Alternative technologies listed with rationale

Gate Result:

• ✅ PASS: All checkboxes checked → Proceed to Tasks
• ⚠️ CONDITIONAL: Resolve conflicts, add missing versions → Re-validate
• ❌ FAIL: Critical vulnerabilities or incompatibilities → Re-evaluate choices

Common Violations and Fixes

Violation 1: Vague Version Specifications

❌ Wrong:

Core Dependencies:
  - Fiber (latest)
  - PostgreSQL driver (current)
  - Zap (newest stable)

✅ Correct:

Core Dependencies:
  - gofiber/fiber/v2@v2.52.0
    Purpose: HTTP router and middleware
    Alternatives Considered: net/http (too low-level), gin (less active)
    Trade-offs: Accepting Express-like API for Go

  - lib/pq@v1.10.9
    Purpose: PostgreSQL driver
    Alternatives Considered: pgx (more complex than needed)
    Constraint: Must remain compatible with database/sql

  - go.uber.org/zap@v1.27.0
    Purpose: Structured logging
    Alternatives Considered: logrus (slower), slog (Go 1.21+ only)
    Trade-offs: Accepting Uber's opinionated API

Violation 2: Missing Security Analysis

❌ Wrong:

JWT Library: golang-jwt/jwt@v5.0.0

✅ Correct:

JWT Library:
  Package: golang-jwt/jwt@v5.2.0
  Purpose: JWT token generation and validation
  Security:
    - CVE Check: Clean (no known vulnerabilities as of 2024-01-15)
    - OWASP: Follows best practices for token handling
    - Updates: Security patches applied within 24h historically
  Alternatives: cristalhq/jwt (no community), lestrrat-go/jwx (complex)

Violation 3: Undefined Infrastructure

❌ Wrong:

Infrastructure:
  - Some database (probably Postgres)
  - Cache (Redis or Valkey)
  - Storage for files

✅ Correct:

Infrastructure:
  Database:
    Product: PostgreSQL 16.1
    Rationale: ACID guarantees, proven stability, team expertise
    Configuration: Single primary + 2 read replicas
    Cost: $450/month (managed service) or $120/month (self-hosted)

  Cache:
    Product: Valkey 8.0
    Rationale: Redis fork, OSS license, compatible APIs
    Configuration: 3-node cluster, 16GB RAM total
    Cost: $90/month (managed) or $45/month (self-hosted)

  Object Storage:
    Product: MinIO (latest stable release branch)
    Rationale: S3-compatible, self-hosted, no vendor lock
    Configuration: 4-node distributed setup, 4TB storage
    Cost: $200/month (infrastructure only)

Dependency Resolution Patterns

For LerianStudio/Midaz Projects (Required)

Mandatory Dependencies:
  - lib-commons: @latest (LerianStudio shared library)
  - lib-auth: @latest (Midaz authentication) - Midaz projects only
  - Hexagonal structure via boilerplate
  - Fiber v2.52+ (web framework standard)
  - Zap v1.27+ (logging standard)

Prohibited Choices:
  - Heavy ORMs (use sqlc or raw SQL)
  - Custom auth implementations (use lib-auth)
  - Direct panic() calls in production code
  - Application-level proxies (handled at cloud/infrastructure)

Version Constraints:
  - Go: 1.24+ (for latest stdlib features)
  - PostgreSQL: 16+ (for JSONB improvements)
  - Valkey: 8+ (Redis 7.0 API compatibility)

General Best Practices

Prefer:
  - Semantic versioned packages (major.minor.patch)
  - Well-maintained packages (commits within 6 months)
  - Minimal dependency trees (avoid transitive bloat)
  - Standard library when sufficient

Avoid:
  - Deprecated packages (marked or unmaintained >1 year)
  - Single-maintainer critical dependencies
  - Packages with >100 transitive dependencies
  - GPL licenses unless compliance is certain

License Compliance

Document all licenses:

License Summary:
  MIT: 45 packages
    - Permissive, commercial use allowed
    - Attribution required in binary distributions

  Apache 2.0: 23 packages
    - Patent grant included
    - Attribution required

  BSD-3-Clause: 12 packages
    - Permissive, attribution required

  Commercial/Proprietary: 2 packages
    - cloud-vendor-sdk: Covered under service agreement
    - monitoring-agent: Free tier for <100 hosts

Compliance Actions:
  - [ ] Attribution file created for distributions
  - [ ] Legal team notified of commercial dependencies
  - [ ] GPL dependencies: None (verified ✓)

Cost Analysis Template

Infrastructure Costs (Monthly):
  Compute:
    - Production: 4 containers × $50 = $200
    - Staging: 2 containers × $25 = $50
    - Total: $250/month

  Storage:
    - Database: $450 (managed PostgreSQL 16)
    - Cache: $90 (managed Valkey cluster)
    - Object: $200 (self-hosted MinIO on $50 VMs)
    - Total: $740/month

  Network:
    - Data transfer: ~$30/month (estimated)
    - Load balancer: $20/month
    - Total: $50/month

  Third-Party Services:
    - Auth provider: $100/month (10k MAU)
    - Email service: $50/month
    - Monitoring: $0 (self-hosted)
    - Total: $150/month

Grand Total: $1,190/month base
Scaling Cost: +$150 per 1000 additional users

Cost Validation:
  - Budget: $2,000/month available
  - Margin: 40% buffer for growth
  - Status: ✅ Within budget

Confidence Scoring

Use this to adjust your interaction with the user:

Confidence Factors:
  Technology Familiarity: [0-30]
    - Stack used successfully before: 30
    - Similar stack with variations: 20
    - Novel technology choices: 10

  Compatibility Verification: [0-25]
    - All dependencies verified compatible: 25
    - Most dependencies checked: 15
    - Limited verification: 5

  Security Assessment: [0-25]
    - Full CVE scan completed: 25
    - Basic security check done: 15
    - No security review: 5

  Cost Analysis: [0-20]
    - Detailed cost breakdown: 20
    - Rough estimates: 12
    - No cost analysis: 5

Total: [0-100]

Action:
  80+: Generate complete dependency map autonomously
  50-79: Present alternatives for key dependencies
  <50: Ask about team expertise and constraints

Output Location

Always output to: docs/pre-development/dependencies/dep-map-[feature-name].md

After Dependency Map Approval

1. ✅ Lock all versions - update only with documented justification
2. 🎯 Create lock files (go.mod, package-lock.json, etc.)
3. 🔒 Set up Dependabot or equivalent for security updates
4. 📋 Proceed to task breakdown with full stack context

Quality Self-Check

Before declaring Dependency Map complete, verify:

• Every dependency has explicit version (no @latest)
• All version conflicts resolved and documented
• Security scan completed (CVE database checked)
• All licenses documented and compliant
• Cost analysis completed with monthly estimates
• Team expertise verified or learning plan exists
• Compatibility matrix complete
• Upgrade constraints documented
• All TRD components have dependencies mapped
• Gate 6 validation checklist 100% complete

The Bottom Line

If you wrote a Dependency Map without explicit versions, add them now or start over.

Every dependency must be specific. Period. No @latest. No version ranges without justification. No "we'll figure it out later".

Vague dependencies cause:

• Non-reproducible builds that work on your machine but fail elsewhere
• Security vulnerabilities from unvetted versions
• Incompatibilities discovered during implementation (too late)
• Impossible debugging when "it worked yesterday"

Be explicit. Be specific. Lock your versions.

Your deployment engineer will thank you. Your future debugging self will thank you. Your security team will thank you.