a-organvm/parametrize-and-cite

Parametrize and Cite

Two universal mandates apply to any data or compilation thereof:

1. All dynamic information is a configurable environment variable. Names, links, statistics, costs, identifiers, dates, thresholds, contact details — never hard-coded. The structure is reusable; the particulars are injected.
2. All assertions require multiple citations. Every factual claim carries at least two independent sources. Single-source claims are flagged, not shipped.

These are not stylistic preferences. They are substrate disciplines that determine whether an artifact survives time (parametrization protects against drift; multi-citation protects against epistemic collapse).

When this skill fires

Apply this skill whenever the input is a "compiled artifact" — anything that bundles structure with particulars:

• pitch decks, one-pagers, sales sheets, README files
• competitive analyses, market reports, research summaries
• configuration files, manifests, deployment templates
• onboarding docs, runbooks, SOPs, playbooks
• any document that mixes "the pattern" with "this specific instance"
• any document that makes claims (numbers, attributions, characterizations)

If the artifact has a brand-shaped surface AND reusable bones, this skill fires. If it makes assertions, this skill fires.

The transformation pipeline

Run the artifact through five phases in order. Don't skip phases — each one catches a different class of issue.

Phase 1: Audit

Read the artifact end-to-end before transforming anything. Build two inventories:

• Dynamic-information inventory: every concrete particular (see the taxonomy below).
• Assertion inventory: every factual claim, with its current citation count.

Note: an "assertion" is anything stated as fact that the reader is expected to believe. Opinions and recommendations are not assertions. Numbers, attributions, comparisons, and historical claims are.

Phase 2: Identify dynamics

Categorize each particular by what makes it dynamic. Use this taxonomy:

| Category | Examples | Env var prefix | |---|---|---| | Identity | company name, person name, project name, brand | IDENTITY_* | | Locator | URL, repo path, email, phone, address | LINK_* / CONTACT_* | | Quantitative | revenue, count, percentage, ratio, score | STAT_* | | Monetary | price, cost, budget, fee, salary | COST_* | | Temporal | date, deadline, duration, period | DATE_* / DURATION_* | | Threshold | limit, quota, target, SLA | THRESHOLD_* | | Credential | API key, token, account ID | SECRET_* (never default) | | Categorical | tier, plan, region, jurisdiction | CATEGORY_* |

Anything that could differ between instances of this artifact's reuse is dynamic, even if it feels permanent today. "Our company name" is dynamic — the artifact might be reused by an acquirer, a fork, a parallel project, or a customer-facing variant.

Phase 3: Parametrize

Replace each dynamic particular with an env-var reference. Choose a template syntax that matches the artifact's medium:

• Markdown / prose docs: {{ IDENTITY_COMPANY_NAME }} (Mustache-style) or ${IDENTITY_COMPANY_NAME} (shell-style)
• YAML / JSON configs: ${IDENTITY_COMPANY_NAME} (envsubst-style) or platform-native (!Ref, ${{ vars.X }}, etc.)
• Code files: language-idiomatic (os.environ["IDENTITY_COMPANY_NAME"], process.env.IDENTITY_COMPANY_NAME)

Generate a paired .env.example (or platform-equivalent: config.example.yaml, terraform.tfvars.example, etc.) with every variable, a one-line comment describing what it controls, and a sample value drawn from the original artifact.

# Identity
IDENTITY_COMPANY_NAME="Example Corp"        # Replaces brand references in headers, footers
IDENTITY_PRODUCT_NAME="ExampleProduct"      # Used in feature descriptions

# Stats — quarterly report figures
STAT_Q4_REVENUE_USD=4200000                 # Q4 top-line revenue
STAT_Q4_GROWTH_PCT=23                       # YoY growth percentage

# Costs — pricing tier defaults
COST_TIER_STARTER_USD_MONTH=49              # Starter plan monthly price

Never inline secrets even as examples. For SECRET_* variables, the example file shows the variable name and a placeholder (SECRET_API_KEY=changeme-in-production), never a real key.

Phase 4: Cite

For every assertion in the inventory, attach at least two independent citations. Define independence carefully:

• Two sources from the same parent org are not independent. A company's own homepage + its own blog = one source.
• A primary source + a secondary that reports on the primary is not two independent sources. That's one source plus its echo.
• Two independent sources = two organizations with no editorial or financial relationship, each having direct access to the underlying evidence (or each citing a distinct primary).

Citation format depends on the medium:

• Prose docs: inline footnotes [^1] + bibliography section
• Slides / decks: source line at bottom of slide, full sources in appendix
• Data tables: per-row source column + per-column source notes
• Code comments: # Source: <url> (accessed YYYY-MM-DD); cross-checked: <url>

Where you cannot find two independent citations, do one of the following — explicitly, never silently:

1. Flag with [CITATION-REQUIRED] in the output and list in a "Verification gap" section.
2. Demote the assertion to a conditional: "If [source] is correct, then…"
3. Remove the assertion if it's load-bearing but unsupportable.

Never invent or fabricate sources. Never paper over with weasel phrases ("studies have shown," "it is widely known").

Phase 5: Emit

Produce four artifacts as a set:

1. The transformed artifact — original content with dynamics parametrized and assertions cited.
2. .env.example (or platform equivalent) — every variable with comment and sample value.
3. CITATIONS.md — full bibliography organized by section, with accessed-dates and brief notes on independence.
4. TRANSFORMATION_LOG.md — what was changed, what was flagged, what was removed, with rationale.

The four-artifact emission is non-negotiable. Shipping the transformed artifact without the .env.example strands the user; without CITATIONS.md the citations are unverifiable; without the log the user can't audit what you changed.

What counts as dynamic — edge cases

Some particulars feel permanent but are dynamic on reuse. Treat each as a variable:

• "The current year" — DATE_PUBLICATION_YEAR, not literal 2026
• "Our team size" — STAT_TEAM_HEADCOUNT, even if it changes annually
• License names — IDENTITY_LICENSE_TYPE, in case the template is reused under different terms
• Tone-of-voice phrases unique to a brand — these are dynamic; the structure of the sentence is reusable
• Compliance thresholds tied to a jurisdiction — THRESHOLD_GDPR_RETENTION_DAYS, in case the template moves to another regime

If you're unsure whether something is dynamic, parametrize it. The cost of an extra env var is near-zero. The cost of a hard-coded value that needed to vary is reissuing the whole artifact.

What counts as an assertion — edge cases

These are assertions and require citation:

• "X is the largest provider in Y market"
• "23% of users churn within 30 days"
• "This complies with regulation Z"
• "Method A is faster than method B"
• "The acquisition closed on date D for price P"

These are NOT assertions (no citation needed):

• "We recommend X because…" (recommendation)
• "Consider whether Y applies to your context" (advice)
• "This document describes our approach to Z" (descriptive)
• "Section 3 covers configuration" (structural)

If a sentence both recommends AND asserts, split it: "Adopt approach X (recommendation). Approach X has been measured at 40% lower latency [^1][^2] (assertion)."

Output verification checklist

Before declaring the transformation complete, verify:

• [ ] Every concrete particular from the original is either parametrized or explicitly retained with rationale
• [ ] .env.example has one line per variable, with comment and sample
• [ ] No secret has a real value in the example file
• [ ] Every assertion has ≥2 independent citations OR is flagged / demoted / removed
• [ ] Bibliography lists every cited source with URL and accessed-date
• [ ] Transformation log enumerates every change
• [ ] Re-reading the transformed artifact with only the env-var names in place still makes structural sense (sentences don't collapse into nonsense when the particulars are abstracted)

The last check matters: if the artifact becomes incoherent when the particulars are removed, the artifact was about the particulars and parametrization is the wrong move — surface this to the user rather than ship a degraded version.

Reference

For detailed pattern examples by artifact type (decks, READMEs, configs, reports), see references/transformation-patterns.md.

For citation-independence judgment calls (when is a source "the same parent org"? when does a secondary count as independent?), see references/citation-independence.md.