Parameterizing Plan Docs

Overview

A plan or implementation doc serves two readers: the historical record of what was built, and the template for re-applying it elsewhere. Hardcoded configurable values (ports, namespaces, repo names, version pins) scattered as body literals break both roles -- the artifact rots as values drift; the template is invisible until a reader hits a collision. This is the best-practice pattern for resolving that tension.

Core principle: Factor configurable parameters into a top-of-doc table documenting the option range and rationale; leave body code blocks with the project's concrete defaults. Body = historical artifact. Top table = template lens. Both stay accurate; neither contaminates the other.

When to Use

• Authoring or maintaining plans, runbooks, implementation docs, or setup guides
• Doc has 3+ references to an environment-specific value
• Reader will reasonably ask "what can I change here?"
• Hardcoded values have caused collisions, drift, or stale references

When NOT to use: single-use scripts; compliance / security / contract docs with mandated fixed values; project-internal conventions baked into code (use CLAUDE.md / AGENTS.md / GEMINI.md instead).

The Pattern

1. Identify configurable parameters. Common categories: ports, namespaces, organization/repo names, version pins, file paths, URLs, secret names, cluster names, region codes, account IDs, environment labels.

1. Insert a parameter section immediately after the metadata block (before content sections):

• Heading: ## <Category> Selection (e.g., Host Port Selection, Namespace Selection, Version Pinning)
• 1-2 sentences of context: what the parameter is, why configurable, what value the body retains
• Table of plausible options, one per row, with a rationale column
• Bold the project's currently-used value alongside its rationale
• Substitution checklist: enumerate the files / sections that need updating once a reader picks their own value

1. Leave body code blocks unchanged. Keep the original concrete value as a deliberate historical anchor. Do NOT replace it with <PLACEHOLDER> syntax -- that breaks copy-paste, removes the doc's value as a faithful artifact, and forces readers to re-render mentally on every reading.

Quick Reference

Common Mistakes

• Placeholder syntax in body code blocks -- breaks copy-paste; defeats the artifact role
• Parameter table buried at the end -- place immediately after metadata
• Single-row "table" -- a range with rationale is the value; one row is hardcoding with extra steps
• No substitution checklist -- readers know "I can change this" but not "where else this threads"
• "Currently used" marker drifting from body -- sync when either side changes

Red Flags

• "Only one parameter is configurable, not worth a table" -- if it varies, document the variance
• "The doc is short, parameterizing is overkill" -- short docs get reused more, not less
• "Readers can just grep" -- they cannot grep for what they do not know is configurable
• "We will refactor the body to use placeholders later" -- placeholders contaminate the artifact role; do not

Real-World Impact

Applied to a 3500-line plan with 30+ references to a single configurable host port (originally hardcoded to a heavily-trafficked dev-tool port), the pattern collapsed re-application from "audit every code block" to "read the top table, run the substitution checklist." Body stayed canonical; table became the template lens.

Cross-Reference

RELATED: superpowers:writing-plans -- general plan-doc structure conventions; this skill refines them on the configurability axis.