Change Documentation Skill

When to Use

Load this skill when working on the documentation playbook rework, when generating or reviewing per-change records (ADRs, changelogs, blast-radius/rollback notes), or when setting up the CI job that publishes in-repo docs to the GitLab Wiki.

How It Works

The Documentation Rework Task

The existing documentation playbook needs a complete rework (SPEC.md §1 — explicitly flagged as the first real authoring task). The current playbook is broken. The rework must produce a playbook that is:

• Idempotent — passes the Molecule idempotence gate (zero changed tasks on second run). (ansible-iac-gitops.md §2; ansible-testing skill)
• FQCN throughout — ansible.builtin.*, ansible.windows.* etc. No bare module names. (ansible-patterns skill)
• OS-aware by structure, not conditionals — separate plays or play includes per OS group; not when: ansible_os_family == "Windows" guards scattered through tasks. (ansible-patterns skill; ansible-iac-gitops.md §1)
• no_log: true on any task that might surface sensitive data in doc generation output. (secrets-vault skill)

Start the rework by: reading the existing documentation playbook → identify all broken patterns (non-idempotent tasks, command/shell where a module exists, missing FQCN, hardcoded paths, OS conditionals without structure) → open an MR with the fix that passes the full gate chain. (DESIGN.md §13)

In-Repo Source of Truth + Wiki Publish

Two artifacts per change:

1. In-repo: ADR (docs/decisions/ADR-NNNN-*.md) and/or CHANGELOG entry committed in the same MR as the change. Generated by the change-scribe agent (haiku tier) from the merged diff via a post-merge hook. (DESIGN.md §13)
2. Published: a CI job mirrors in-repo docs to the GitLab Wiki after merge.

# .gitlab-ci.yml (doc-publish job)
publish-wiki:
  stage: verify
  tags: [linux, docker, ci]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - |
      # Do NOT put the token in the clone URL (it leaks into the process list / job log).
      # Pass it as a masked+protected header on a project access token scoped to the wiki.
      git -c http.extraheader="Authorization: Bearer ${WIKI_TOKEN}" \
        clone "https://${CI_SERVER_HOST}/${CI_PROJECT_PATH}.wiki.git" wiki
      cp -r docs/decisions wiki/
      cp CHANGELOG.md wiki/
      cd wiki && git add -A && git commit -m "sync from ${CI_COMMIT_SHA}" \
        && git -c http.extraheader="Authorization: Bearer ${WIKI_TOKEN}" push

The Wiki is human-readable; the in-repo files are version-controlled and git-diffable. Both are audit evidence: the Wiki provides a browsable view; the repo preserves history.

Per-Change Record Format

Every merged change should produce a record with:

• What: summary of tasks/files changed (from diff).
• Why: rationale / issue reference (from MR description).
• Blast radius: which hosts/groups affected; which services restarted.
• Rollback: git revert <sha> or re-run previous artifact; specific service recovery.
• ARA run: linked pipeline ID + commit SHA.

The change-scribe agent (haiku) generates this from the merged diff automatically. Human review is required before the record is committed. (DESIGN.md §13)

<!-- docs/decisions/ADR-0042-nginx-tls-hardening.md -->
# ADR-0042: Enforce TLS 1.2+ on Nginx

Date: 2026-06-03
Status: Accepted
Pipeline: #101 | Commit: abc1234

## What
Updated `corp_nginx` role to enforce TLS 1.2+ minimum and disable SSLv3/TLS 1.0/1.1.

## Why
Resolves drift finding from drift-check pipeline 2026-05-28; aligns with PCI DSS Req 4.2.1.

## Blast Radius
Hosts: `web01, web02, web03` (group: webservers). Service: nginx restart triggered.
Windows targets: none.

## Rollback
`git revert abc1234` → normal MR + pipeline flow. Or re-run pipeline artifact
`ansible-bundle-prev1234.tar.gz` in GitLab Environments UI.

ARA Integration for Change Records

Tag every ARA run with commit SHA + pipeline ID to join "what/when" to GitLab's "who/why":

ARA_DEFAULT_LABELS="commit=${CI_COMMIT_SHA},pipeline=${CI_PIPELINE_ID},change=ADR-0042" \
  ansible-playbook -i inventories/prod site.yml

ARA records task-level detail; the change record ties ARA to the MR approval and the Octopus deployment log. Together these satisfy PCI DSS Req 6 change control evidence. (ansible-iac-gitops.md §4; pci-dss-devops.md §2)

Trust Boundary

• Documentation is generated from diffs and run output — it never contains secrets.
• no_log: true on any task that might capture credentials to ARA/console.
• The Wiki publish job uses a scoped GITLAB_TOKEN with write-to-wiki permission only.
• Change records are proposals from change-scribe; a human must review before commit.
• Per-change records include rollback instructions — this is the audit-evidence package for each deployed change. (SPEC.md §2; DESIGN.md §13)

Examples

# Correct rework pattern for documentation playbook
# (replace any command/shell tasks with idempotent modules)
- name: Ensure documentation directory exists (idempotent)
  ansible.builtin.file:
    path: /var/doc/infra
    state: directory
    owner: root
    group: root
    mode: '0755'

# Wrong — non-idempotent, breaks check mode
- name: Generate docs (BROKEN — do not use)
  ansible.builtin.command: ./generate-docs.sh   # command/shell breaks idempotency

TODO: Read the existing documentation playbook and identify all broken patterns before proposing the rework MR. TODO: Define the doc-generation tooling (e.g., ansible-doctor, role2spec, or custom template) once the desired output format is confirmed from the team. TODO: Add the change-scribe post-merge hook wiring once the hook is built (SPEC.md §3 hooks table — change-scribe-hook not yet implemented). TODO: Confirm GitLab Wiki push credentials scope (scoped token vs deploy key).

Deep Reference

PCI Change Control Evidence Requirements (Req 6.5)

Every MR must include or reference all of the following before merge:

• Description of the change and its purpose
• Risk assessment (blast radius, affected systems)
• Test results (--check --diff output as minimum; Molecule results for new roles)
• Back-out / rollback plan
• Authorized approvers (minimum 2; author cannot self-approve)

The per-change YAML record produced by change-scribe captures all of these. Attach the YAML record to the MR description as a code block.

ADR When to Write One

Write an ADR when a decision:

• Changes a pattern used by multiple playbooks or roles
• Adds or removes a compliance control
• Changes the trust model (e.g., adding a new runner, changing auth method)
• Would surprise a future contributor reading the code

Do NOT write an ADR for: adding a task to an existing role, updating a package version, renaming a variable.