operation-manual


Type	Skill
Plugin	awl-project-management · v0.0.12
Invoke	`/awl-project-management:operation-manual`
Source	plugins/awl-project-management/skills/operation-manual/SKILL.md

When Claude uses it

Create an AWL Operation Manual (Betriebshandbuch) for a project. Covers Service Desk, 2nd/3rd level support documentation for mobile apps, CMS, web applications, backend services, and infrastructure. Triggers: “create operation manual”, “operation manual”, “betriebshandbuch”, “ops manual”, “create ops doc”, “write operations manual”.

Trigger phrases: create operation manual · operation manual · betriebshandbuch · ops manual · create ops doc · write operations manual

Definition

Creates an Operations Manual (Betriebshandbuch) following the AWL standard template. Used by Service Desk and 2nd/3rd-level support when a project is in production.

The document scales to what is known. Not all sections apply to every project. Unknown sections are marked > TODO so the team can complete them later.

Step 0 — Detect Existing Manual → Update Mode

Before asking for sources, check whether an operation manual already exists for this project (ClickUp page, docs/operation-manual.md in the repo, etc.).

If one exists, switch to update mode instead of starting from scratch:

Read the existing manual’s Version and Last updated date from its header. If earlier version snapshots exist as ClickUp sub-pages, they’re available as reference for what changed between versions.
Tell the user the time period since the last update (e.g. “Last updated 2026-01-15 — 6 months ago”) and ask which sources to check for changes in that period. Typical additions on top of the original sources:
- ClickUp lists: Service Backlog, Product Backlog, Sprint list(s)
- Slack channels (same internal + dev channels as before)
- GitLab (commits/MRs since the last update)
Scan only for changes within that time period — not a full re-discovery of everything. In ClickUp, filter tasks by date; in Slack, search within the date range; in GitLab, check commit/MR history since the last update date.
Update only the affected sections (section-by-section merge, same rule as Step 5). Bump the version and add a changelog line summarizing what changed.
Skip Steps 1–3 below except for anything the update-mode scan didn’t cover — ask only for genuinely new gaps.

If no manual exists yet, proceed to Step 1 as normal (first-time creation).

Step 1 — Ask for Input Sources

Ask the user what they can provide. Any combination is valid:

What sources can you share for this project?

- Google Drive: folder link or specific document links (architecture, existing ops docs, contracts)
- ClickUp: project or product documentation folder link
- GitLab: group or repo link (or I'll use the current working directory)
- Slack: internal project channel + dev channel names (most projects have both)
- Anything else: existing docs, diagrams, notes

Do not proceed until you have at least one source, or the user explicitly says to start from scratch.

Step 2 — Extract Info From Provided Sources

Process each provided source:

Google Drive

Use the Google Drive MCP to read shared documents and, for a folder link, to search files scoped to that folder.

Extract: contacts, architecture info, SLA/contracts, hosting details, 3rd party services, any existing operation manual content.

When referencing a Drive file in the manual, use its full URL (https://drive.google.com/file/d/{id}/view), never the bare file ID.

ClickUp folder/project

Use the ClickUp MCP to read the workspace hierarchy and documentation pages.

Look for: deployment notes, infrastructure docs, known issues, 3rd party service configs, contacts.

Note the exact URL of every ClickUp task and wiki page found (not just its title) — needed for links in Step 4.

GitLab / local repo

From the current working directory or a GitLab link, read:

CLAUDE.md, README.md — architecture, commands, environments
.env.example, docker-compose*.yml, CI configs (.gitlab-ci.yml) — services, env vars, pipelines
package.json, requirements.txt, etc. — tech stack
Existing docs: docs/, wiki/, files with “operation”, “betrieb”, “manual” in the name

Slack channels

Most projects have two channels — read both:

Internal project channel (e.g. #proj-pestalozzi): client communication, decisions, infrastructure discussions
Dev channel (e.g. #dev-pestalozzi): deployment announcements, technical issues, known bugs, workarounds

Use the Slack MCP to read channels and search public/private messages for:

Deployment instructions or announcements
Infrastructure setup discussions
Incident reports and post-mortems
3rd party service setup or issues
Production warnings or restrictions that were communicated

Step 3 — Ask for Missing Critical Info

After extracting from all sources, ask only for what’s still missing:

Always needed (if not found):

Project name (customer + product)
Client contacts (name, role, email)
AWL responsible (PM or TL)
Staging and production environment URLs

If not found in sources:

Hosting provider
3rd party services in use
1Password vault name for this project

Mark everything else unknown as > TODO: [what's needed] — don’t block on it.

Step 4 — Generate the Document

Include only sections relevant to this project. Skip sections that clearly don’t apply (e.g. no “Translations” section for a pure API, no “Mobile App” details for a web-only project).

Include a table of contents near the top, listing only the sections actually included, each linking to its heading.

Reference any ClickUp task or page as the raw URL (e.g. https://app.clickup.com/t/...), not as markdown link syntax — ClickUp’s editor doesn’t render [title](url) as a clickable link, but auto-links a bare URL.

At the top of the document, include:

Version: current version number (start at v1.0, bump minor for updates, e.g. v1.1)
Last updated: today’s date + author (Claude Code, on behalf of [user])
Created with: a short note that this manual was generated with Claude Code, listing the input sources actually used (e.g. “GitLab repo awl-ecosystem/foo, ClickUp project docs, #dev-foo Slack channel”)
Changelog: one line per update — version, date, and what changed (e.g. “v1.1 — 2026-08-10 — hosting provider changed, Sentry setup added”). Add a new line on every update instead of silently overwriting old info — this is the only place a change is visible when other sections just link out to content that itself changed.

When a topic is already documented on an existing ClickUp wiki page (e.g. Tech-Stack, architecture), don’t duplicate the content — link to that page instead, inline where the topic comes up.

Write the whole document in a single language — see Document Rules.

Standard Sections

Administrative Notes

Contacts: Client-side (IT, PM, business owner) + AWL responsible
Maintenance dates: Agreed maintenance windows
Contracts / SLA: Link to AWL Cockpit or contract document

System Overview

Repositories table: purpose → GitLab path
Architecture diagram link (if found in Drive or ClickUp)
Tech-Stack: frontend, backend, CMS, database, infra
Environments table: Environment × Component × URL

3rd Party Services

One subsection per service:

Purpose in this project
Credentials: 1Password vault name + item name (never actual values)
Key environment variables
Known issues or quirks

Monitoring & Logging

Tools: Sentry, StatusCake, Grafana, Azure Monitor, CheckMK, etc.
Log locations per environment
Slack alert channels (reference the channels gathered in Step 2)

Database

Type, hosting, backup strategy

Assets / Storage

Bucket/container names and purposes (S3, MinIO, GCS, Azure Blob)

SLA, Contracts, Domains, SSL

Contract link, SSL provider, DNS management

Data Regulation

Personal data? GDPR relevant? Data retention policy?

Backups

What, how often, restore reference

Statistics & Metrics

Analytics tools (GA, Plausible, etc.)

Incident Management

Outage communication flow
Common fault categories specific to this project
Escalation path

Production Deployments

Timing or approval restrictions
Who must be notified

Local Development

Short setup summary or link to repo README, tunnel setup if needed

Deployment

Branch → environment pipeline
Initial deployment checklist (migrations, seeders, first admin user, etc.)

Jobs / Scripts / Batch Files

Scheduled/automatic jobs (cron, Celery beat, etc.)
Manual scripts and when to run them

Translations (only if project has i18n)

Tool (Loco, Phrase, etc.) and sync workflow

Troubleshooting

Known issues: symptom → cause → solution
Useful log queries

Step 5 — Deliver

Ask where to save:

GitLab repo: Write to docs/operation-manual.md
Markdown: Print for copy-paste into Google Docs or ClickUp
ClickUp Document: Create via ClickUp MCP in the project space

If a ClickUp operation manual page already exists, never overwrite or delete it wholesale. Merge section-by-section: read the existing page, and for each Standard Section, update/append it in place if it already exists, or add it if missing. Leave any existing content that isn’t covered by the Standard Sections untouched.

Snapshot: since the live manual links out to content on other ClickUp pages (wiki, architecture docs, etc.), it doesn’t preserve history on its own. After delivering, always ask the user: “Snapshot of this version create?” If yes, create a ClickUp sub-page under the operation manual titled Operation Manual — v{version} — {date} (e.g. Operation Manual — v1.1 — 2026-08-10), containing the full resolved content of that version — inline the content of any linked pages instead of just linking to them, so the sub-page is a complete, standalone record of what the manual said at that point in time, including its own table of contents. Only create it if the user confirms.

Document Rules

No secrets — reference 1Password vault + item name only, never actual credentials
No guessed URLs — only URLs from user input or config files
Partial info is fine — > TODO: [description] is better than invented content
Language — one language for the whole document, never mixed. Default to English; only use German if the client/team explicitly works in German.
Production warnings — use > ⚠️ callouts for deployment restrictions
Keep it current — every edit updates the “Last updated” field at the top; treat a stale date as a signal the manual needs a review pass