portfolio/docs/codex/task-template.md

Task Templates

Copy the relevant section into a future Codex request and fill in the blanks.

Operational Bash Tool

Goal

Build or improve a Bash tool for:

Context

Affected platform, incident, or operational workflow:

Constraints

• Default to dry-run/read-only.
• Require --execute for changes.
• Use OK, WARNING, and CRITICAL.
• Exit 0 OK, 1 operational issue, 2 invalid input or missing dependency.

Files/directories to inspect

• infra-run/scripts/bash/
• Relevant runbook or README:

Implementation steps

1. Inspect neighboring scripts and shared helpers.
2. Add or adjust usage/help output.
3. Add discovery, pre-check, guarded change, post-check, and reporting sections where useful.
4. Update README or runbook notes.

Validation commands

bash -n <script>
./scripts/check-bash.sh

Done when

The tool is readable, safe by default, validates inputs, reports clearly, and has updated docs.

Ansible Playbook/Role

Goal

Add or improve Ansible automation for:

Context

Target OS and inventory group:

Constraints

• Preserve check-mode friendliness.
• Prefer modules over shell/command.
• Keep playbooks short.
• Keep role defaults sanitized.

Files/directories to inspect

• infra-run/ansible/README.md
• infra-run/ansible/inventory/
• infra-run/ansible/playbooks/
• infra-run/ansible/roles/

Implementation steps

1. Inspect existing role/playbook patterns.
2. Add defaults, tasks, handlers, and tags only where needed.
3. Add validation or post-check tasks for operational evidence.
4. Update role/playbook README.

Validation commands

./scripts/check-ansible.sh
cd infra-run/ansible && ansible-playbook --syntax-check -i inventory/hosts.yml playbooks/<playbook>.yml

Done when

The playbook targets the right hosts, is idempotent where practical, supports review with --check --diff, and docs explain limitations.

Runbook

Goal

Create or improve a runbook for:

Context

Incident signal, platform, and affected service:

Constraints

• Include pre-checks, decision points, rollback, post-checks, and evidence.
• Avoid pretending lab notes are production-certified.

Files/directories to inspect

• infra-run/runbooks/
• infra-run/docs/
• Related scripts/examples:

Implementation steps

1. Define scope and assumptions.
2. Add triage steps and command examples.
3. Add safe execution gates.
4. Add validation and handoff notes.

Validation commands

./scripts/check-docs.sh

Done when

An operator can follow the runbook without guessing the risk, inputs, or success criteria.

Lab Scenario

Goal

Add or improve a lab scenario for:

Context

Technology and local environment:

Constraints

• Mark lab-only behavior clearly.
• Keep prerequisites and cleanup explicit.

Files/directories to inspect

• labs/
• labs/docs/lab-cheatsheet.md

Implementation steps

1. Document prerequisites and topology.
2. Add setup, validation, failure injection if relevant, and cleanup.
3. Link related scripts or runbooks.

Validation commands

./scripts/check-docs.sh

Done when

The lab is reproducible enough to review and does not imply production readiness.

Platform Project

Goal

Add or improve a platform project for:

Context

Monitoring, storage, clustering, virtualization, observability, or related topic:

Constraints

• Keep status honest: planned, partial, lab-tested, or complete.
• Prefer operational notes over marketing language.

Files/directories to inspect

• platform-projects/
• platform-projects/docs/platform-cheatsheet.md

Implementation steps

1. Identify scope and current maturity.
2. Add design notes, operational workflows, and validation.
3. Link runbooks, examples, and known limitations.

Validation commands

./scripts/check-docs.sh

Done when

The project explains what exists, how to validate it, and what remains unproven.

Documentation Cleanup

Goal

Clean up documentation for:

Context

Current confusion, duplication, or missing links:

Constraints

• Preserve useful operational detail.
• Avoid tutorial-style filler.

Files/directories to inspect

• Root README.md
• Section README files
• Related docs/runbooks:

Implementation steps

1. Remove duplication where it hurts navigation.
2. Add links to canonical docs.
3. Make limitations explicit.
4. Update changelog if meaningful.

Validation commands

./scripts/check-docs.sh

Done when

Readers can find the right tool, runbook, or validation command quickly.

Repository Review

Goal

Review repository quality for:

Context

Areas of concern:

Constraints

• Findings first, ordered by severity.
• Include file/line references where possible.
• Do not rewrite unrelated content.

Files/directories to inspect

• AGENTS.md
• README.md
• infra-run/
• platform-projects/
• labs/
• scripts/

Implementation steps

1. Inspect structure and conventions.
2. Review safety, validation, docs, and maintainability.
3. Patch only low-risk issues if requested.
4. Report risks and follow-ups.

Validation commands

./scripts/validate-repo.sh
git diff --stat

Done when

The review identifies practical risks and leaves a clear next action list.