Design and Build

Design and Build

Overview

This skill implements the Technical Solution (TS), Product Integration (PI), and Configuration Management (CM) process areas from the CMMI-based SDLC prescription.

Core principle: Architecture decisions require documentation (ADRs). Emergency shortcuts require retrospective documentation. "Best practice" is never justification - requirements are.

Reference: See docs/​sdlc-prescription-cmmi-levels-2-4.md Section 3.2 for complete policy and practice definitions.

---

When to Use

Use this skill when:

• Making architecture or design decisions (technology choice, patterns, structure)
• Setting up build/​integration systems (CI/​CD, deployment pipelines)
• Managing technical debt (tracking, prioritization, paydown)
• Establishing configuration management (branching strategy, release process)
• Facing "should we use X?" questions where X is trendy technology
• Team experiencing git chaos, integration hell, or debt spiral

Do NOT use for:

• Implementation details within existing architecture → Use domain-specific skills (python-engineering, web-backend)
• Testing strategy → Use quality-assurance skill
• Requirements or specification → Use requirements-lifecycle skill

---

Quick Reference

---

Level-Based Governance

CRITICAL: This skill enforces governance based on project maturity level.

Level Detection

Check for project level in:

1. CLAUDE.md: CMMI Target Level: 3
2. User message: "This is a Level 3 project..."
3. Default if unspecified: Level 3

ADR Requirements by Level

Emergency Exception Protocol (HOTFIX Pattern)

When: Production emergency, immediate fix needed, no time for full ADR process

Level 3 Requirements:

1. Fix the emergency (restore service)
2. Document the fix in issue tracker with "HOTFIX" label
3. Create retrospective ADR within 48 hours:
   • Incident timeline
   • Why proper fix wasn't feasible
   • Technical debt introduced
   • Paydown commitment with date (max 2 weeks)
4. Track paydown as high-priority ticket

Violation: Skipping retrospective ADR = governance failure. See Enforcement section below.

HOTFIX Frequency Limit: >5 HOTFIXes per month = systemic problem requiring architectural audit, not process exception.

What Counts as "Architectural Decision"? (Level 3)

Architectural decisions (ADR required):

• Technology platform choice (language, framework, database, cache, message queue)
• Branching strategy (GitFlow, GitHub Flow, trunk-based)
• CI/​CD platform (GitHub Actions, Azure Pipelines, Jenkins)
• Deployment strategy (blue/​green, canary, rolling)
• Design patterns with broad impact (event-driven, microservices, monolith)
• Module boundaries and interfaces (how system decomposes)
• Authentication/​authorization approach (OAuth, JWT, session-based)
• Data storage strategy (SQL vs NoSQL, caching strategy, data partitioning)

Implementation details (no ADR required, track in code/​PR):

• Specific library choice within chosen framework (e.g., logging library in Python)
• Variable/​function naming conventions
• Code organization within module (file structure)
• Test framework choice (if it doesn't affect architecture)

Borderline decisions (when in doubt, write ADR):

• If change affects >3 modules or files → ADR
• If reversal would take >1 day → ADR
• If future developers would ask "why did they choose this?" → ADR

---

Enforcement and Escalation

Level 3 Requirements:

• Platform enforcement: Branch protection, CI gates, ADR linking
• Process enforcement: ADR review before implementation, HOTFIX tracking
• Metrics: % architectural changes with ADRs (target: 100%)
• Violations escalate: Team lead → Engineering manager → Governance committee

For detailed enforcement mechanisms, escalation paths, and compliance metrics, see level-scaling.md.

---

Anti-Patterns and Red Flags

Resume-Driven Design

Detection: User says "I've heard X is best practice" or "Everyone uses Y"

Red Flags:

• Technology mentioned before requirements
• Appeal to popularity ("everyone uses microservices")
• Buzzword bingo (serverless, Kubernetes, blockchain)
• Can't articulate WHAT PROBLEM they're solving

Counter:

1. "What requirements drive this choice?"
2. "What alternatives exist?"
3. "Why is current approach inadequate?"
4. If they can't answer → "You're doing resume-driven design. Requirements first, technology second."

Forcing function: Require ADR with alternatives analysis. If they can't justify with measurable requirements, ADR review will reject it.

Architecture Astronaut

Detection: Over-engineered solution for simple problem

Red Flags:

• Microservices for CRUD app
• Service mesh for 2 services
• Event sourcing for simple data model
• "Future-proof" without concrete future requirements

Counter: "What's the SIMPLEST solution that meets requirements? Start there. Add complexity when demonstrated need exists, not hypothetically."

Cowboy Coding

Detection: No reviews, no standards, "works on my machine"

Red Flags:

• Skipping pull requests
• Force pushing to main
• No CI/​CD
• "I'll add tests later"

Counter: Enforce basic CM practices. Level 2 minimum: branch protection, required PR reviews, CI runs on PRs.

Debt Spiral

Detection: Increasing % of time on bugs, velocity declining

Red Flags:

• 50% time on bugs = WARNING

• 60% time on bugs = CODE RED

• Every feature breaks something else
• Team morale declining

Counter: See Technical Debt Management reference sheet. CODE RED triggers feature freeze.

---

Reference Sheets

Load these on-demand for detailed guidance:

---

Common Mistakes

---

Integration with Other Skills

---

Real-World Impact

Without this skill: Teams experience:

• Undocumented architecture decisions that haunt future developers
• Resume-driven design leading to over-engineered solutions
• Git chaos with daily conflicts and lost work
• Debt spirals consuming 70%+ of time
• Emergency shortcuts becoming permanent anti-patterns

With this skill: Teams achieve:

• Defensible audit trail through ADRs
• Technology choices driven by requirements, not hype
• Structured configuration management reducing conflicts by 80%+
• Early crisis detection preventing debt spirals
• Emergency protocols that maintain governance without blocking urgency

---

Next Steps

1. Determine project level: Check CLAUDE.md or ask user for CMMI target level (default: Level 3)
2. Identify situation: Use Quick Reference table to find relevant reference sheet
3. Load reference sheet: Read detailed guidance for specific domain
4. Enforce ADR requirements: Level 3 requires ADR for architectural decisions - no exceptions without HOTFIX protocol
5. Apply decision frameworks: Use systematic evaluation, not gut feelings or hype
6. Counter anti-patterns: Watch for resume-driven design, debt spirals, cowboy coding
7. Measure success: Establish baseline, set targets, schedule retrospectives

Remember: "Best practice" is never justification. Requirements are. If you can't articulate the requirement, you can't justify the architecture.