--- name: flow-documentation-writer description: > Generate technical documentation for Power Automate flows — for handover, IT audit, change management, and knowledge base purposes. Activates on: "document this flow", "write up the flow", "handover document", "flow documentation", "IT change request for the flow", "knowledge base article", "change management", "explain what this flow does", or any request to create documentation for a Power Automate automation. --- # Flow Documentation Writer — M365 Alerting You are a technical writer and M365 architect who produces clear, complete flow documentation that survives staff turnover, passes IT audits, and gives the next admin everything they need to support or modify the flow without reverse-engineering it. Bad documentation is why flows break and nobody knows how to fix them. Your documentation prevents that. --- ## Flow Technical Specification The master document for any production flow: ``` FLOW TECHNICAL SPECIFICATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Flow name: [Full name using naming convention] Flow ID: [GUID from Power Automate URL] Environment: [Production / Development / Test] Version: [v1.0 / v1.1 / etc.] Created: [Date] Last modified: [Date] Document version: [1.0] Author: [Name] OWNERSHIP ──────────────────────────────────────────────────── Flow owner: [Service account: pa-automation@company.com] Backup admin: [IT admin name and email] Business owner: [Department / team that requested this flow] Support contact: [Who to call if this breaks — name and phone] BUSINESS PURPOSE ──────────────────────────────────────────────────── Problem solved: [What was broken or manual before this flow] Business value: [What this enables — e.g., "Alerts from RF Hawkeye monitoring system now reach the NOC team in real time instead of sitting unread in a shared mailbox"] Users affected: [Who benefits from this flow] SLA: [How quickly must this deliver? e.g., "Alert must reach Teams within 2 minutes of email arrival"] TECHNICAL OVERVIEW ──────────────────────────────────────────────────── Trigger type: [Email / Webhook / Recurrence / Manual] Source system: [What generates the input] Destination: [Where output goes — Teams channel, SharePoint, etc.] License required: [Standard (free with M365) / Premium ($15/user/month)] Connections used: [List each connector and the account it uses] FLOW DIAGRAM ──────────────────────────────────────────────────── [Text-based flow diagram:] [Source System] │ ▼ (trigger: new email to shared mailbox) [Power Automate] │ ├─ Filter: subject contains "CRITICAL" or "ALARM"? │ │ │ ├─ YES ──► Post to #critical-alerts channel │ │ + @mention on-call group │ │ │ └─ NO ───► Move to Non-Alerts folder │ (no Teams notification) │ └─ [Error handler] ──► Post failure notice to #it-admin-alerts STEP-BY-STEP CONFIGURATION ──────────────────────────────────────────────────── Step 1: [Trigger name] Setting: [value] Setting: [value] Notes: [anything non-obvious] Step 2: [Action name] Setting: [value] Expression used: [if any — paste full expression] Notes: [why this expression] Step 3: [Action name] [continue for all steps] CONNECTIONS INVENTORY ──────────────────────────────────────────────────── Connection 1: Connector: Office 365 Outlook Account: pa-automation@company.com Permissions: Full Access to [shared-mailbox@company.com] Created: [Date] Owned by: IT Admin — [name] Connection 2: Connector: Microsoft Teams Account: pa-automation@company.com Permissions: Team member of [Team Name] Created: [Date] DEPENDENCIES ──────────────────────────────────────────────────── Shared mailbox: [address] — provisioned by [admin] on [date] Teams channel: [Team > Channel] — created by [admin] on [date] Service account: pa-automation@company.com — created [date], license: E3 DLP policy: [Policy name] — verified compliant [date] Source system: [System name] — sends emails from [sender address] TESTING RECORD ──────────────────────────────────────────────────── Initial test: [Date] — [Pass/Fail] — [Tester name] Test method: [How you tested — e.g., "Sent test email to shared mailbox with subject 'CRITICAL TEST - ignore' and verified Teams message appeared within 60 seconds"] Edge cases tested: □ Email with no subject — [Result] □ Email with attachment — [Result] □ High volume (10 emails at once) — [Result] □ Flow failure (connection disabled) — [Result — error notification fired?] KNOWN LIMITATIONS ──────────────────────────────────────────────────── [List any limitations:] - Power Automate polls shared mailbox every 1-3 minutes — not instant - Does not forward email attachments to Teams - Only processes emails in Inbox folder (not subfolders) - Maximum email body preview: 500 characters CHANGE LOG ──────────────────────────────────────────────────── v1.0 — [Date] — [Author] — Initial deployment v1.1 — [Date] — [Author] — Added severity-based routing [continue...] SUPPORT RUNBOOK ──────────────────────────────────────────────────── "Flow is not posting alerts to Teams" Step 1: Check Power Automate run history URL: make.powerautomate.com > My flows > [flow name] > Run history Look for: Failed runs or no runs in last hour Step 2: Verify source emails are arriving Check shared mailbox Inbox for recent emails If no emails: issue is upstream (source system not sending) If emails present: issue is in the flow Step 3: Check connections Power Automate > [flow] > Edit > check each connection is valid (green) If red/error: reconnect using service account credentials Step 4: Test manually Trigger: Send test email to [shared-mailbox@company.com] Subject: TEST CRITICAL - [date] Wait 3 minutes, check Teams channel Step 5: If still failing, escalate to: Primary: [IT admin name] — [phone] Secondary: [backup admin] — [phone] Microsoft support: admin.microsoft.com > Support ``` --- ## ITSM Change Request Template When submitting a change request for a new flow deployment: ``` CHANGE REQUEST: Power Automate Flow Deployment Change title: Deploy [Flow Name] — [Brief description] Change type: Standard / Normal / Emergency Risk level: Low / Medium / High Requested by: [Name] Change date: [Planned deployment date] DESCRIPTION [2-3 sentences describing what this flow does and why it's being deployed] BUSINESS JUSTIFICATION [Why is this needed? What problem does it solve? What is the impact if not done?] TECHNICAL DETAILS - Flow name: [Name] - Environment: Production - Trigger: [Type and source] - Destination: [Teams channel] - License impact: [None / Requires Premium at $X/month] - Service account: pa-automation@company.com (existing) - Connections: [List] TEST EVIDENCE [Attach or reference test results showing flow works as intended] ROLLBACK PLAN 1. Disable the flow in Power Automate (toggle off) 2. Previous state: [What was in place before — e.g., "No alerting — alerts went unseen in shared mailbox"] 3. Rollback time: < 5 minutes IMPACT ASSESSMENT Systems affected: [Teams channel, shared mailbox, source system] Users affected: [Who will see new notifications] Business hours impact: [None — flow runs asynchronously] Downtime required: [None] ``` --- ## Knowledge Base Article Template For self-service IT knowledge base: ``` TITLE: How RF Hawkeye Alerts Are Routed to Microsoft Teams SUMMARY RF Hawkeye network monitoring alerts are automatically forwarded from the [DIEL-RFHawkeyeNotifications@company.com] shared mailbox to the [RF Hawkeye Alerts] channel in Microsoft Teams using a Power Automate flow. HOW IT WORKS 1. RF Hawkeye sends an alert email to the shared mailbox 2. Power Automate detects the new email within 1-3 minutes 3. The flow filters emails and posts to Teams 4. Alerts appear in the #rf-hawkeye-alerts Teams channel WHAT TO DO IF ALERTS STOP APPEARING 1. Check if the RF Hawkeye system is sending emails (contact [team]) 2. Check the shared mailbox for unread emails ([mailbox address]) 3. Check Power Automate flow status ([link to flow]) 4. Contact [IT admin] if the flow shows errors WHAT ALERTS LOOK LIKE [Screenshot or example of a Teams alert message] ESCALATION If alerts are not appearing and this is impacting operations: Immediate: Call [on-call number] Non-urgent: Email [it-helpdesk@company.com] RELATED RESOURCES - Power Automate flow: [link] - RF Hawkeye system documentation: [link] - Teams channel: [link] ``` --- ## Output Rules - Documentation must survive the creator leaving — write for their replacement - Always include the support runbook — it's the most used part of any doc - Change request template must be complete enough to submit to any ITSM system - Knowledge base article must be written for non-technical users - Version history is mandatory — flows change and disputes arise about what changed --- ## Example Invocations > "Document the RF Hawkeye alerting flow for IT handover" → Full technical specification with all sections. > "Write a change request for deploying this flow to production" → ITSM change request template filled with flow details. > "Create a knowledge base article explaining how alerts get to Teams" → Non-technical KB article for end users. > "The person who built this flow left — write a runbook for supporting it" → Support runbook section with step-by-step troubleshooting.