---
name: ops-manual-writer
description: "Guidance for writing OpenStack operations manual procedures following NASA document standards. Use when authoring per-service procedures, maintenance workflows, or operational documentation that must be verified against running infrastructure."
user-invocable: true
allowed-tools: Read Grep Glob
metadata:
extensions:
gsd-skill-creator:
version: 1
createdAt: "2026-02-22"
triggers:
intents:
- "write procedure"
- "operations manual"
- "document procedure"
- "nasa procedure format"
- "ops manual"
- "maintenance procedure"
contexts:
- "writing operations documentation"
- "creating service procedures"
- "documenting OpenStack operations"
---
# Operations Manual Writer
This skill guides agents producing operations manual content for the GSD OpenStack Cloud Platform. Every procedure must follow NASA document standards adapted for cloud operations per SP-6105 SS 5.5 (Product Transition) and NPR 7123.1 Process 9 (Product Transition). The operations manual is the primary handoff artifact between the deployment crew and the operations crew.
The goal is consistency and verifiability: every procedure an operator follows must be structured so that another agent (doc-verifier) can confirm the procedure matches the running system, and another operator can execute it without ambiguity.
## Procedure Format Template
Every operational procedure follows the standard format derived from NASA-STD-3001 (adapted for cloud operations) as specified in the project reference document (Section 3.4 of gsd-openstack-nasa-reference.md):
```
PROCEDURE ID: OPS-{SERVICE}-{NUMBER}
TITLE: {What this procedure accomplishes}
SE PHASE: Phase E (Operations & Sustainment)
NPR REFERENCE: NPR 7123.1 SS 3.2 Process 9 (Product Transition)
LAST VERIFIED: {YYYY-MM-DD} against {OpenStack release version}
VERIFIED BY: {doc-verifier agent / manual verification}
PURPOSE
{One to three sentences explaining why an operator would perform this
procedure and when it should be executed.}
PRECONDITIONS
1. {System state required before starting}
2. {Services that must be running}
3. {Access credentials or permissions needed}
4. {Backup state confirmed if procedure is destructive}
SAFETY CONSIDERATIONS
- {What could go wrong during this procedure}
- {Data loss risks and mitigation}
- {Service disruption scope and duration}
- {Dependencies that may be affected}
PROCEDURE
Step 1: {Exact command or action}
Expected result: {What the operator should see}
If unexpected: {What to do -- specific recovery action or escalation}
Step 2: {Exact command or action}
Expected result: {What the operator should see}
If unexpected: {What to do}
Step N: ...
VERIFICATION
1. {How to confirm the procedure succeeded}
2. {Specific command and expected output}
3. {Service health check to run after completion}
ROLLBACK
1. {How to undo the procedure if needed}
2. {Steps in reverse order with commands}
3. {How to confirm rollback succeeded}
REFERENCES
- {Related OPS procedures by ID}
- {Related runbooks by RB-{SERVICE}-{NNN} ID}
- {OpenStack documentation URL}
- {SP-6105 or NPR 7123.1 section reference}
```
### Procedure ID Format
- Pattern: `OPS-{SERVICE}-{NUMBER}`
- SERVICE: Uppercase service name (KEYSTONE, NOVA, NEUTRON, CINDER, GLANCE, SWIFT, HEAT, HORIZON, KOLLA, GENERAL)
- NUMBER: 3-digit sequential number per service, starting at 001
- Cross-service procedures use GENERAL prefix
- Example: `OPS-KEYSTONE-001`, `OPS-NOVA-003`, `OPS-GENERAL-002`
## Writing Standards
These rules are mandatory for all procedure authoring. Violations cause verification failures.
### Language Rules
1. **Imperative mood for all procedure steps.** Write "Run", "Verify", "Check" -- never "You should run" or "The operator runs".
2. **Exact commands only.** Every step must include the precise command or action. Never write "configure as needed" or "adjust accordingly".
3. **Expected results for every step.** State what the operator should see after executing the step. Include example output where practical.
4. **If-unexpected branches for failure-prone steps.** Any step that could fail must include a recovery path: retry, escalate, or redirect to a troubleshooting runbook.
5. **No assumptions about operator knowledge.** Spell out paths, service names, and configuration file locations. Do not assume the operator knows where files are stored.
### Safety Rules
6. **Safety considerations before any destructive operation.** If a procedure can cause data loss, service disruption, or configuration damage, the safety section must be populated.
7. **Backup confirmation before destructive steps.** Any procedure that modifies data or configuration must confirm backup state in preconditions.
8. **Rollback section is mandatory.** Every procedure must have a rollback path. If a procedure is truly irreversible, the rollback section must state this explicitly with justification.
### Reference Rules
9. **All external references must include NASA document identifiers.** Cross-references to NASA methodology use SP-6105 SS {section} or NPR 7123.1 SS {section} format.
10. **OpenStack documentation links must be specific.** Link to the exact page, not the top-level docs site. Include the OpenStack release name when relevant.
11. **Related procedures linked by ID.** Use OPS-{SERVICE}-{NUMBER} for operations manual cross-references and RB-{SERVICE}-{NNN} for runbook cross-references.
## Per-Service Procedure Categories
Each OpenStack service in the operations manual requires procedures in these standard categories. This ensures consistent coverage across all services.
### Required Categories
| Category | Frequency | Description |
|----------|-----------|-------------|
| Service Health Check | Daily | Verify service is running, API responds, logs show no errors |
| Configuration Verification | After changes | Confirm configuration matches expected state after any modification |
| Backup and Restore | As scheduled | Create backup of service data/config and verify restore capability |
| Upgrade (Minor) | Per release | Apply minor version updates with pre-check, upgrade, post-verify |
| Upgrade (Major) | Per release cycle | Apply major version updates with extended testing and rollback plan |
| Troubleshooting Common Failures | On demand | Diagnose and resolve the 3-5 most common failure modes per service |
| Security Audit | Monthly | Verify security configuration, certificates, RBAC policies, and access logs |
### Service-Specific Additions
Some services require additional procedure categories beyond the standard set:
- **Keystone:** Token rotation, federation configuration, catalog management
- **Nova:** Live migration, flavor management, hypervisor maintenance
- **Neutron:** Network topology changes, floating IP management, security group audit
- **Cinder:** Volume migration, backend failover, snapshot management
- **Glance:** Image format conversion, metadata management, backend rotation
- **Swift:** Ring rebalancing, replication monitoring, container quota management
- **Heat:** Stack template validation, resource dependency analysis, orphan cleanup
- **Horizon:** Session management, custom panel deployment, theme configuration
## Verification Requirements
Procedures are not complete until they are verified. This section defines how verification works within the documentation lifecycle.
### Verification Process
1. **Every procedure must have a verification section** that proves the procedure succeeded. The verification section contains specific commands with expected output.
2. **Procedures must be testable against a running system.** A procedure that cannot be verified against the actual infrastructure is incomplete.
3. **The doc-verifier skill handles automated verification.** When a procedure is marked for automated verification, doc-verifier extracts the verification commands and runs them against the system.
4. **Last-verified date and system version must be recorded.** The LAST VERIFIED field in the procedure header tracks when the procedure was last confirmed accurate.
5. **Unverified procedures must carry a visible warning.** If a procedure has not been verified against the current system version, add a warning block at the top.
### Unverified Warning Format
```
WARNING: This procedure has not been verified against the current system.
Last verified: {date} against {version}.
Current system: {version}.
Use with caution and verify each step manually.
```
## Output Location
All operations manual procedures are written to `docs/operations-manual/` following the filesystem contracts:
| File | Content |
|------|---------|
| `docs/operations-manual/keystone-procedures.md` | All OPS-KEYSTONE-* procedures |
| `docs/operations-manual/nova-procedures.md` | All OPS-NOVA-* procedures |
| `docs/operations-manual/neutron-procedures.md` | All OPS-NEUTRON-* procedures |
| `docs/operations-manual/cinder-procedures.md` | All OPS-CINDER-* procedures |
| `docs/operations-manual/glance-procedures.md` | All OPS-GLANCE-* procedures |
| `docs/operations-manual/swift-procedures.md` | All OPS-SWIFT-* procedures |
| `docs/operations-manual/heat-procedures.md` | All OPS-HEAT-* procedures |
| `docs/operations-manual/horizon-procedures.md` | All OPS-HORIZON-* procedures |
Each file contains all procedures for that service, ordered by procedure number.
## Cross-References
| Resource | Purpose |
|----------|---------|
| `skills/methodology/nasa-se/SKILL.md` | SE lifecycle phase context -- procedures map to Phase E (Operations & Sustainment) per SP-6105 SS 5.4-5.5 |
| `skills/methodology/doc-verifier/SKILL.md` | Automated verification methods for procedure accuracy against running infrastructure |
| `skills/methodology/runbook-generator/SKILL.md` | Runbook format alignment -- procedures reference runbooks for troubleshooting branches |
| `docs/filesystem-contracts.md` | Output location contracts for `docs/operations-manual/` directory |
| NASA SP-6105 SS 5.5 | Product Transition process -- operations documentation as transition artifact |
| NPR 7123.1 SS 3.2 Process 9 | Product Transition requirements -- procedures satisfy handoff documentation |
| NASA-STD-3001 (adapted) | Procedure format origin -- adapted from crew procedures standard for cloud operations |