cd-anti-pattern-page

# CD Anti-Pattern Page Generator Role: implementation. This skill generates new content files following the anti-pattern page template. Generate a new anti-pattern page for the "Quality and Delivery Anti-Patterns" section of the CD migration guide. ## Constraints 1. **Follow the template exactly.** Do not invent new sections or skip required ones. 2. **Be concise.** Generate the page and report validation results. No preambles. 3. **Validate before finishing.** Run all validation checks in the instructions before considering the work complete. ## Instructions 1. **Read the canonical example** at `content/en/docs/problems/push-based-work-assignment.md` to calibrate tone, depth, and structure. 2. **Read `common-issues.md`** at the repo root to find the issue description if the user references an issue number or name. 3. **Ask the user** which anti-pattern to write if not already specified. 4. **Generate the page** following the template below. 5. **Validate before finishing:** - Run `/grammar-check` on the generated file to catch and fix any prohibited punctuation. - Verify all internal links point to existing pages. - Confirm the "Why this is a problem" section has all three required subsections plus the CD impact closing subsection. ## Template ```markdown --- title: "[Anti-Pattern Name]" linkTitle: "[Anti-Pattern Name]" weight: [number matching common-issues.md issue number] description: > [One-sentence description of the anti-pattern] --- {{% pageinfo %}} **Category:** [Category Name] | {{% risk-indicator level="[critical|high|medium|low]" %}} {{% /pageinfo %}} ## What this looks like [2-3 paragraphs describing observable symptoms. Be specific and concrete - describe what a team member would actually see, hear, or experience. Use present tense.] Common variations: - **[Variation name].** [Description] - **[Variation name].** [Description] [Telltale sign paragraph: "The telltale sign: ..."] ## Why this is a problem [1-2 sentence framing paragraph that sets up the subsections below.] ### It reduces quality [How this anti-pattern degrades quality. Be specific about the mechanism. Contrast with the healthier alternative in the final paragraph of this subsection.] ### It increases rework [How this anti-pattern causes wasted or duplicated effort. Contrast with the healthier alternative.] ### It makes delivery timelines unpredictable [How this anti-pattern disrupts flow and predictability. Contrast with the healthier alternative.] ### [Optional: context-specific impact subsection] [Additional impacts that don't fit the three required dimensions above. Use when the anti-pattern has a distinctive effect worth calling out separately. Skip if the three required subsections already cover the key impacts.] ### Impact on continuous delivery [How this specifically blocks CD adoption or practices. This is always the final subsection. Connect back to the core CD requirements: steady flow of small changes, fast feedback, predictable delivery.] ## How to fix it ### Step 1: [Action verb] [Concrete first step. Include specific actions the team should take.] ### Step 2: [Action verb] [Continue with ordered steps. Each step should build on the previous one.] [Include an objection-handling table if the anti-pattern has common pushback:] | Objection | Response | |-----------|----------| | "[Common pushback]" | [Concrete response that addresses the concern] | [Include a role transition table if applicable:] | Before | After | |--------|-------| | [Old behavior] | [New behavior] | ## Measuring progress | Metric | What to look for | |--------|-----------------| | [Metric name] | [What improvement looks like] | ## Related content - [Links to relevant guide pages in the site] ``` ## Content Guidelines ### Tone - Direct, specific, and assertive but not preachy - Write as a practitioner advising a peer, not a consultant lecturing a client - State what happens and why it matters - let the reader draw conclusions - Use "you" and "the team" naturally ### Depth per section - **What this looks like:** 2-3 paragraphs plus variations. Enough detail that a reader says "that's us." - **Why this is a problem subsections:** 2-4 paragraphs each. Each subsection should have a clear mechanism (how the anti-pattern causes this effect) and a contrast with the healthier alternative. - **How to fix it steps:** 3-6 ordered steps, concrete enough to start Monday morning. Step headings must not include timeline labels such as "(week 1)", "(weeks 2-4)", "(month 2+)", or "(ongoing)". Cadence labels for a repeating action, such as "(monthly)", and "(Optional)" are allowed. In step text, tie each action to a condition (data gathered, a state reached, a result observed) rather than a fixed number of weeks, sprints, or months. - **Measuring progress:** 4-6 metrics. Link to reference metric pages where one exists. - **Related content:** 3-5 links to existing guide pages. ### Style rules - Use sentence-style capitalization in headings (only capitalize the first word and proper nouns). - Keep paragraphs to 3-4 sentences maximum. - Use active voice. - Run `/grammar-check` before finishing to catch prohibited punctuation (endashes, emdashes, hyphens used as dashes). ### Subsection conventions - "Why this is a problem" always has three required subsections: "It reduces quality", "It increases rework", "It makes delivery timelines unpredictable" - Optional extra subsections go between "delivery timelines" and "Impact on continuous delivery" - "Impact on continuous delivery" is always the final subsection - Each subsection contrasts the anti-pattern with the healthier alternative - "How to fix it" uses ordered steps with no timeline labels in step headings (see Depth per section) ## Quality Impact Levels Each anti-pattern gets a risk indicator badge. Choose the level based on how directly the anti-pattern blocks continuous delivery: | Level | When to use | |-------|-------------| | Critical | Foundational blocker - CD is impossible without fixing this (e.g., no CI, no pipeline) | | High | Significant drag on delivery flow, feedback loops, or quality (e.g., PR bottlenecks, too much WIP) | | Medium | Impedes delivery but less directly tied to core CD gates (e.g., no vertical slicing) | | Low | Minor friction - worth fixing but not a delivery blocker | ## Categories These match the categories in `common-issues.md`: 1. Delivery Speed & Frequency (issues 1-8) 2. Branching & Integration (issues 9-15) 3. Testing & Quality (issues 16-27) 4. Work Decomposition & Planning (issues 28-35) 5. Pipeline & Infrastructure (issues 36-48) 6. Monitoring & Observability (issues 49-54) 7. Organizational & Cultural (issues 55-69) 8. Compliance & Security (issues 70-75) 9. Architecture (issues 76-83) 10. Developer Experience (issues 84-90) 11. Legacy & Migration-Specific (issues 91-97) 12. Missing Practices (issues 98-105) ## Available Metrics Pages (for linking) Use relative links from the problems directory: `../../reference/metrics/[page]/` - `build-duration` - Build Duration - `change-fail-rate` - Change Fail Rate - `development-cycle-time` - Development Cycle Time - `integration-frequency` - Integration Frequency - `lead-time` - Lead Time - `mean-time-to-repair` - Mean Time to Repair - `release-frequency` - Release Frequency - `work-in-progress` - Work in Progress ## Available Guide Pages (for Related Content links) Use relative links from the problems directory: `../../[section]/[page]/` **Assess:** - `assess/baseline-metrics` - Baseline Metrics - `assess/current-state-checklist` - Current State Checklist - `assess/identify-constraints` - Identify Constraints - `assess/value-stream-mapping` - Value Stream Mapping **Foundations:** - `foundations/build-automation` - Build Automation - `foundations/code-review` - Code Review - `foundations/everything-as-code` - Everything as Code - `foundations/testing-fundamentals` - Testing Fundamentals - `foundations/trunk-based-development` - Trunk-Based Development - `foundations/work-decomposition` - Work Decomposition - `foundations/working-agreements` - Working Agreements **Pipeline:** - `pipeline/application-config` - Application Config - `pipeline/deployable-definition` - Deployable Definition - `pipeline/deterministic-pipeline` - Deterministic Pipeline - `pipeline/immutable-artifacts` - Immutable Artifacts - `pipeline/pipeline-architecture` - Pipeline Architecture - `pipeline/production-like-environments` - Production-Like Environments - `pipeline/rollback` - Rollback - `pipeline/single-path-to-production` - Single Path to Production **Optimize:** - `optimize/architecture-decoupling` - Architecture Decoupling - `optimize/feature-flags` - Feature Flags - `optimize/limiting-wip` - Limiting WIP - `optimize/metrics-driven-improvement` - Metrics-Driven Improvement - `optimize/retrospectives` - Retrospectives - `optimize/small-batches` - Small Batches **Continuous Deployment:** - `continuous-deployment/agentic-cd` - Agentic CD - `continuous-deployment/deploy-on-demand` - Deploy on Demand - `continuous-deployment/experience-reports` - Experience Reports - `continuous-deployment/progressive-rollout` - Progressive Rollout **Reference:** - `reference/cd-dependency-tree` - CD Dependency Tree - `reference/common-blockers` - Common Blockers - `reference/dora-capabilities` - DORA Capabilities - `reference/glossary` - Glossary - `reference/resources` - Resources ## Output Write the generated page to `content/en/docs/problems/[slug].md` where `[slug]` is the anti-pattern name in kebab-case.