# 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
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

```bash
./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

```bash
./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

```bash
./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

```bash
./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

```bash
./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

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

### Done when

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