# Documentation > Documentation - Skill: `itential/documentation` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add itential/documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/itential/documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: itential (https://skillmd.com/u/itential) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/itential/documentation --- # Documentation **Purpose:** Read Itential assets → discover relationships → group into use cases → produce documentation **Output:** `customer-spec.md` (inferred HLD per use case) + `solution-design.md` (as-built LLD per use case) + `README.md` (master index, only when multiple use cases) **Feeds into:** Can be handed to `/spec-agent` for refinement or `/solution-arch-agent` for redesign ## Customization Before using this skill, check `custom/org/`, `custom/team/`, and `custom/dev/` in this skill's own directory. Read every `.md` file found, in that order (any folder may be empty or absent). Apply them in addition to everything below — where a file overrides a specific rule from this document, prefer the override; more specific wins (dev over team over org). See `.claude/CUSTOMIZATION.md` for the full framework and what belongs in which layer. --- ## CRITICAL: Output Requirements **The ONLY deliverables are markdown files.** Do NOT produce JSON index files, JSON catalogs, or any intermediate artifacts. All analysis happens in-memory. ``` {reports-directory}/ README.md ← master index of all use cases ONLY when more than one use case {use-case-slug}/ customer-spec.md ← inferred HLD (business purpose, scope, requirements) solution-design.md ← as-built LLD (components, flows, adapters, data model) {use-case-slug}/ customer-spec.md solution-design.md ... ``` **Never write JSON files as output.** No `workflow-index.json`, no `asset-index.json`, no `use-case-groups.json`. The user wants documentation, not data dumps. --- ## What This Does Surveys **global** Itential assets — workflows, JSON forms, transformations, templates, command templates, analytic templates, Operations Manager automations, golden configuration trees and compliance plans, and LCM resource models that live outside named projects. Accepts `all`, `platform`, a directory path, or a list of specific global asset names. Discovers how they relate to each other, groups them into logical use cases, and produces documentation for each group plus a master index when there are multiple use cases. > **For a named project:** Use `/project-to-spec` instead — it reads a single project's components and produces customer-spec.md + solution-design.md tailored to that project. --- ## Flow ``` User invokes /documentation ['all' | 'platform' | directory | specific global asset names] | ├── Step 0: Determine Scope | ├── Project named? → redirect to /project-to-spec | ├── Specific global assets named? → resolve + discover relationships → ask grouping preference | └── 'all' / platform / directory? → full collection + grouping flow | ├── Step 1: Collect + classify global assets (in-memory) ├── Step 2: Discover relationships + group into use cases (in-memory) ├── Step 3: Present proposed groupings to engineer for approval ├── Step 4: Write per-use-case reports (customer-spec.md + solution-design.md) ├── Step 5: Write master README.md (ONLY when more than one use case) └── Step 6: Present summary to engineer for review ``` --- ## Step 0: Determine Scope Before collecting assets, determine what the user wants to document. ### Pattern 1 — Project named If the user names a specific project, **redirect them to `/project-to-spec`** — that skill is purpose-built for single-project documentation and produces a more thorough analysis. > "It looks like you want to document a specific project — use `/project-to-spec` for that. It reads the project's components directly and produces a more thorough customer-spec.md and solution-design.md for it." ### Pattern 2 — Specific global asset(s) named If the user provides one or more asset names or IDs: 1. Resolve each asset via the platform API or local files 2. Traverse the relationship graph starting from each named asset (childJob links, OM→workflow, LCM→workflow, golden config→command template, etc.) 3. Present the discovered asset cluster to the engineer: - List all assets found (named + discovered via relationships) - Show how they connect 4. Ask the engineer: > "I found these assets and their relationships. How should I document them?" > - **(Default) Group into use cases** — analyze and cluster into logical groups, then produce HLD+LLD per group > - **Document as a single unit** — treat the entire cluster as one use case, produce one HLD+LLD > - **Document each asset independently** — produce separate minimal documentation per asset without cross-linking Proceed based on the engineer's answer. ### Pattern 3 — All globals / platform / directory If the user says `all`, `platform`, or provides a directory path, run the full collection and grouping flow (Steps 1–6) without asking about grouping preference. --- ## Step 1: Collect and Classify Assets Ask the engineer for the asset source if not specified. Two modes: ### Mode A — Local Directory Scan for asset JSON files organized by type: ``` directory/ workflows/ *.json json_forms/ *.json transformations/ *.json or *.jst.json templates/ *.json command_templates/ *.json operations_manager_automations/ *.json golden_config/ *.json lcm/ *.json ``` If the directory is flat (all JSON at root), classify by JSON structure signatures below. If a `projects/` subfolder exists, scan it too. Project manifest files (containing `name` + `components[]`) identify which assets belong to a project — use that grouping when building the relationship graph. Strip `@projectId:` prefixes from any workflow names found inside. ### Mode B — Platform API Authenticate using `.auth.json` (see AGENTS.md auth reuse pattern). Fetch global assets (ensure you fetch pagination if there are a lot of assets): ``` GET /automation-studio/workflows?exclude-project-members=true&limit=500 GET /automation-studio/templates?limit=500 GET /automation-studio/json-forms?limit=500 GET /operations-manager/automations GET /mop/templates GET /golden-config/trees GET /golden-config/plans GET /lifecycle-manager/model GET /automation-studio/projects?limit=500 ``` > **Visibility caveat:** see AGENTS.md's "Project Visibility" section. Global assets (this skill's focus) aren't ACL-restricted, so the global catalog isn't undercounted by RBAC — but `GET /automation-studio/projects?limit=500` is per-project-ACL-filtered. Since this skill targets globals, projects are out of scope by default; if the engineer names a specific project they expect, route to `/project-to-spec` instead. ### Classification Signatures | Asset Type | Identifying Fields | |---|---| | **Workflow** | `tasks` (object), `transitions` | | **JSON Form** | `schema`, `struct`, `uiSchema` | | **Transformation** | `incoming`, `outgoing`, `steps` | | **Template** | `type` (textfsm/jinja2), `template` field | | **Command Template** | `commands[]` with `rules[]` | | **Analytic Template** | `commands[]` with `analytics[]` or `baseline` fields | | **OM Automation** | `triggers[]`, `componentName` | | **Golden Config Tree** | `nodes[]`, `rootNode`, `treeType` | | **Golden Config Compliance Plan** | `planType`, `configSpec`, `devices[]` | | **LCM Resource Model** | `resourceType`, `actions[]`, `schema` | **Build the asset index in-memory only.** For each asset, note: name, file path/ID, type, and key metadata. --- ## Step 2: Discover Relationships and Group ### Relationship Discovery Build a relationship graph in-memory connecting all assets: 1. **Workflow → Workflow (childJob links):** For each workflow task where `name === "childJob"` AND `app === "WorkFlowEngine"`, extract child workflow name from `variables.incoming.workflow`. Strip `@projectId:` prefixes. 2. **Workflow → JSON Form:** Tasks where `app === "JsonForms"` or name contains `RenderJsonSchema`/`JsonForm`. 3. **Workflow → Template:** Tasks where `app === "TemplateBuilder"` (renderJinjaTemplate, applyTemplate, applyTextFSMTemplate). 4. **Workflow → Transformation:** Tasks where `name === "transformation"`. 5. **Workflow → Command Template:** Tasks referencing MOP operations (runCommandTemplate). 6. **OM Automation → Workflow:** `componentName` field names the target workflow. Trigger types reveal entry mode: schedule, endpoint (webhook/API), manual (with optional formId). 7. **LCM Resource Model → Workflow:** Each LCM action has an `actionWorkflow` field naming an IAP workflow → link. 8. **Golden Config Compliance Plan → Command Template:** Plans reference MOP command templates for configuration checks → link. 9. **Workflow → Golden Config:** Workflows calling golden-config API tasks via adapter → link. 10. **Adapter patterns:** Collect tasks where `location === "Adapter"` — extract `app` (type name) and operation name. 11. **Naming prefix clustering:** Split on ` - ` (space-dash-space). Assets sharing a prefix are candidates for the same use case. ### Grouping Rules (apply in order) 1. **OM Automations as Entry Points:** Each OM automation's `componentName` → root workflow → traverse childJob graph → collect all reachable workflows + referenced forms/templates/transformations/command templates = one cluster. 2. **LCM Resource Models as Entry Points:** Each LCM model → action workflows → traverse childJob graph → collect all reachable assets = one cluster. If a workflow cluster already contains these workflows, merge the LCM model into that cluster. 3. **Golden Config Clusters:** Golden config trees + their compliance plans + referenced command templates → one cluster. If workflows reference these golden config assets, merge into the same cluster. 4. **Expand by Naming Prefix:** Add ungrouped assets sharing the same naming prefix as assets already in a cluster. 5. **Ungrouped Workflow Trees:** Any root workflow (no parent) with children → new cluster. 6. **Shared Utilities:** Workflows appearing in 3+ clusters → "Shared Utilities" group. Also include: generic TextFSM templates, utility transformations (math, array ops), common utilities (MongoDB CRUD, credential retrieval, notifications). 7. **Test / Standalone:** Workflows with developer name prefixes, `[TEST]`/`test-`/`dummy` patterns, Jira ticket patterns, or <5 tasks with no children and no triggers → "Standalone / Test Workflows" (catalog only, no full HLD/LLD). 8. **Remaining Ungrouped:** Group by functional similarity or list as individual entries in master README. ### Analyze the Components Work through the components to reconstruct intent and structure. #### Identify the orchestrator Find the parent workflow — usually the one that: - Has no `childJob` references pointing to it from other workflows - References other workflows via `childJob` tasks - Has the most complex transition graph For LCM clusters, the resource model itself is the anchor — its action workflows are the orchestrators. For golden config clusters, the compliance plan anchors the cluster. #### Map the data flow For the orchestrator and each child: 1. What are the **inputs**? (inputSchema properties) 2. What adapters are called? (location: "Adapter" tasks) 3. What utility tasks are used? (merge, query, evaluation, childJob, makeData) 4. What are the **outputs**? (outputSchema properties, `$var.job.x` assignments) 5. What external systems are touched? (adapter names → infer ServiceNow, Route53, etc.) #### Infer the phases Each major section of the orchestrator maps to a phase: - A `childJob` to a child workflow = one phase - An `evaluation` branch = a decision point - An adapter call cluster = an integration phase - A `ViewData` = an approval gate - Error handling branches = rollback/recovery phases - An LCM action = a lifecycle phase - A compliance plan check = a validation phase #### Reconstruct acceptance criteria From the workflow structure, infer what "done" looks like: - What does the final outgoing variable represent? - What adapters were called? → "ServiceNow ticket created and updated" - What verifications exist? → `evaluation` tasks checking status - What is the `outputSchema`? → these are the observable outcomes --- ## Step 3: Present Groupings to Engineer **Stop and present the proposed groupings before writing any reports.** Ask: 1. "Here are the use case groups I identified — does this look right?" 2. "These assets are ungrouped — should any be added to an existing group?" — default no 3. "These appear to be test/dev workflows — should I catalog or skip them?" — default skip Show each group with: name, category (Core/Specialized/Shared/Reference), approximate asset count, and 1-line description. **Wait for engineer approval before proceeding to Step 4.** --- ## Step 4: Write Per-Use-Case Reports For each approved use case group, create a directory (or write directly to reports root if only one use case) with two markdown files. ### Produce `customer-spec.md` Write professional, narrative documentation — not mechanical spec sheets. The HLD should read like a business-facing document with rich prose, detailed tables, and domain-specific context. → See template in `helpers/documentation-output-templates.md` — **"customer-spec.md Template"** **For test/standalone use cases**, use a simplified catalog format — asset table with Purpose and Adapters columns only. No full HLD needed. ### Produce `solution-design.md` Write the as-built LLD — this is factual, not inferred. Each component should have at least a sentence description, so an engineer could understand the full system without reading the source JSON. → See template in `helpers/documentation-output-templates.md` — **"solution-design.md Template"** #### Generating Section D: Execution Flow The guidance and example are in the Section D placeholder in `helpers/documentation-output-templates.md`. Do not add a sequence diagram to the HLD (`customer-spec.md`). Section 2 of the HLD is a narrative paragraph only. --- ## Step 5: Write Master README **Only write this step when there are 2 or more use cases.** Create `README.md` at the root of the reports directory. → See template in `helpers/documentation-output-templates.md` — **"README.md Template"** --- ## Step 6: Present to Engineer Show a summary: 1. **Asset inventory** — total files analyzed per type 2. **Use case groups** — count and names 3. **Reports produced** — list of directories/files with customer-spec.md + solution-design.md 4. **Excluded assets** — what was skipped 5. **Gaps** — "I don't see rollback logic or notifications." Ask the engineer to review the reports. Next steps: - **Accept** — use the reports as-is - **Refine** — hand specific use case specs to `/spec-agent` - **Redesign** — hand to `/solution-arch-agent` - **Organize into projects** — proceed to Step 7 --- ## Step 7: Organize Global Assets into Projects (Optional) After the engineer accepts the use case groupings and reviews the reports, ask: > "Would you like me to create a project for each use case and move the assets in? Moving assets into a project renames them with an `@projectId:` prefix — anything currently referencing those assets by name will need updating. Shared utility assets will stay global. Should I proceed?" If no, stop here. The documentation stands as-is. If yes, for each approved use case group (skip "Shared Utilities"): **1. Create the project:** ``` POST /automation-studio/projects {"name": "{use-case-name}", "description": "{one-line from customer-spec.md}", "thumbnail": "", "backgroundColor": "#FFFFFF"} ``` Save `data._id` as `projectId`. **2. Add components:** ``` POST /automation-studio/projects/{projectId}/components/add { "components": [ {"type": "workflow", "reference": "{workflow-id}", "folder": "/"}, {"type": "template", "reference": "{template-id}", "folder": "/"}, {"type": "mopCommandTemplate", "reference": "{mop-name}", "folder": "/"} ], "mode": "move" } ``` Component type values: see AGENTS.md Rule 13. **3. Build a reference impact report before moving anything:** Before executing any moves, scan all global workflows, OM automations, and LCM models to find references that will break. For each asset being moved, find: - **Workflows** with a `childJob` task where `variables.incoming.workflow` matches the asset's current name - **OM automations** where `componentName` matches the asset's current name - **LCM models** where any `actions[].actionWorkflow` matches the asset's current name Produce a table: | Asset being moved | Referenced by | Field | New name after move | |------------------|--------------|-------|-------------------| | `VLAN_Provision_Parent` | `Monthly_Audit` (workflow) | childJob.workflow | `@abc123: VLAN_Provision_Parent` | | `DNS_Create` | `DNS Automation` (OM automation) | componentName | `@abc123: DNS_Create` | Show this to the engineer **before** proceeding: > "Moving these assets will break the following references. I won't fix them automatically — you'll need to update these manually after the move. Here's what needs changing:" **4. Execute the moves** (after engineer confirms they've noted the impact): For each group, run the `POST .../components/add` calls as above. **5. After all groups are processed, show a final summary:** | Use Case | Project ID | Assets Moved | Broken References to Fix | |----------|------------|-------------|--------------------------| | {name} | {id} | {count} | {count} — see impact report above | Flag anything that couldn't be moved (already in a project, API error) for manual follow-up. **Warnings to keep in mind:** - Shared Utilities stay global — do not move them - Assets already in a project cannot be moved again — skip and report - Cross-project references (workflow in one project referencing a workflow in another) must use the full `@{otherProjectId}: {name}` format --- ## What to Watch For - **Orphaned workflows:** No childJob parent AND no OM trigger. May be standalone utilities, abandoned, or externally invoked. Check adapter usage to infer purpose. - **`@projectId:` prefixed names:** Strip prefix (everything through colon+space) before matching. - **Empty componentName:** Fall back to trigger names, `actionId`, or automation name. - **Duplicate/backup workflows:** Names with "Backup", date suffixes, version numbers → note as backups, don't give own group. - **Cross-use-case shared workflows:** Document fully in primary group, add cross-references in others. - **Transformation `.jst.json` naming:** Match on internal `name` field, not filename. - **Template `data` field:** Often a JSON string, not parsed object — parse before analyzing. - **Large TextFSM libraries:** Group under Shared Utilities, not individual use cases. - **Command template rules:** Each rule encodes a compliance check — valuable for HLD requirements. - **LCM `actionWorkflow` may be missing:** If a LCM action has no linked workflow, note the gap — the action is defined but not implemented. - **Golden config trees without compliance plans:** Document the structure but note there is no automated compliance enforcement. - **Workflow descriptions and task summaries are the best source of business intent** — use them heavily. - **Non-hex task IDs:** Task IDs like `apush` or `myTask` are a known bug pattern (`$var` references silently fail on these). - **Static values as indicators:** Hard-coded strings in merge tasks or newVariable tasks often reveal business rules (e.g., `"value": "production"` → production-only path). - **Missing error transitions:** Note any adapter tasks without error transitions — this is a quality gap in the existing implementation. --- ## Gotchas - **Global assets are not access-restricted; projects are** (see AGENTS.md Project Visibility). If the engineer names a specific project they expect, route to `/project-to-spec` rather than declaring it absent. - **NEVER produce JSON files as output.** Only markdown reports. - **childJob `workflow` is the primary relationship link.** Don't trace `$var` references across workflows. - **Naming prefix is a heuristic, not a rule.** Prioritize childJob graph over naming when they conflict. - **OM automations can have multiple triggers.** Document all of them. - **Not every asset connects.** Don't force them into groups — catalog in Shared Utilities or Reference. - **When unsure about golden config or LCM relationships**, ask the engineer rather than guessing. - **Master README is only for multiple use cases.** Single use case → write files directly in reports directory, no subdirectory, no README.