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

Situation	Primary Reference Sheet	Key Decision
"Should we use microservices?"	Architecture & Design	Requires ADR. Use decision framework: team size, domain complexity, ops maturity.
"Git workflow is chaos"	Configuration Management	Diagnose root cause first. GitFlow (L3 releases) vs GitHub Flow (continuous) vs Trunk (high maturity). Requires ADR.
"70% of time on bugs"	Technical Debt Management	CODE RED. Feature freeze, architectural audit, classify debt (architectural/tactical/unpayable).
"Setting up CI/CD"	Build & Integration	Requirements gathering first. Platform choice requires ADR. Start simple, add stages incrementally.
"Quick fix vs proper solution"	Level 2→3→4 Scaling	Level 3 requires retrospective ADR within 48 hours. Document as HOTFIX with paydown commitment.

---

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

Level	ADR Required For	Exception Protocol
Level 2	Major architecture decisions (platform choice, deployment strategy)	Informal discussion OK, document decision in wiki/README
Level 3	ALL architectural decisions (tech stack, branching strategy, design patterns, CI/CD platform)	Emergency HOTFIX: Retrospective ADR within 48 hours mandatory
Level 4	Everything in L3 + quantitative justification with metrics	No exceptions - statistical baselines required

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:

Reference Sheet	When to Use	Link
Architecture & Design	Making technology choices, selecting patterns, designing system structure	architecture-and-design.md
Implementation Standards	Establishing coding standards, code review process, documentation requirements	implementation-standards.md
Configuration Management	Git chaos, branching strategy decisions, release management	configuration-management.md
Build & Integration	Setting up CI/CD, build optimization, deployment pipelines	build-and-integration.md
Technical Debt Management	Team spending >40% time on bugs, debt accumulating, velocity declining	technical-debt-management.md
Level 2→3→4 Scaling	Understanding what rigor is appropriate for your project tier	level-scaling.md

---

Common Mistakes

Mistake	Why It Fails	Better Approach
"Emergency exempts process"	Creates pattern where "urgent" = skip governance, accumulating undocumented debt	Use HOTFIX pattern: retrospective ADR within 48 hours, mandatory
"I'll document it later"	Later never comes, loses audit trail	Document NOW (ADR takes 15 min) or schedule retrospective (48 hours max)
"This is too simple for ADR"	Simple decisions have big impact, lose rationale for future	If it's truly simple, ADR takes 10 min. If it takes longer, it wasn't simple.
"Everyone uses X, so we should"	Resume-driven design, not requirements-driven	Require measurable justification. "Everyone" is not a requirement.
"20% debt allocation" when 70% bugs	Treats crisis as normal problem, ensures slow death	>60% bugs = CODE RED. Feature freeze, not incremental paydown.
"Pick branching strategy" without diagnosis	Treats symptom (conflicts) not cause (architecture? communication?)	Root cause analysis FIRST. Git strategy is symptom, not disease.
Generic CI/CD template without context	Wastes time on wrong solution	Requirements gathering FIRST: build characteristics, deployment context, risk profile

---

Integration with Other Skills

When You're Doing	Also Use	For
Designing Python architecture	axiom-python-engineering	Python-specific patterns and idioms
Designing web API	axiom-web-backend	REST/GraphQL best practices
Making architecture decision	governance-and-risk	Formal DAR process for critical choices
Setting up testing	quality-assurance	Test strategy and coverage
Choosing platforms	platform-integration	GitHub vs Azure DevOps specifics

---

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.