Menu
Document new features, changed functionality, or fix documentation mistakes. Determines scope automatically: new pages, updates to existing pages, cross-cutting changes, or targeted fixes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Add a new documentation guide version (e.g., 7.x). Creates version folder, config, wrappers, updates version selector, netlify.toml, Dockerfile, and home page descriptions.
Remove a deprecated guide version from the documentation site. Deletes version content, updates version selector, netlify.toml, Dockerfile, and adds redirects for the removed version's URLs.
Document a new Wallarm Node release end-to-end: analyze Jira release issues, verify artifacts are published, write changelog, bump version tags across docs, update related pages.
| name | update-feature-docs |
| description | Document new features, changed functionality, or fix documentation mistakes. Determines scope automatically: new pages, updates to existing pages, cross-cutting changes, or targeted fixes. |
You are updating Wallarm product documentation. The task may be any of:
This skill can be used as a step-by-step workflow by an AI agent or as a checklist by a human contributor working without an agent. Steps with code snippets are mechanical; steps that say "ask the author" are decision points where product knowledge is required.
The author provides one or more of:
The author does NOT need to specify which files to edit, section, or filename โ you determine that yourself.
The repo itself is your product knowledge base. Wallarm documentation already maps features, integrations, terminology, and relationships between areas. Read the repo first, ask the author only about things the repo cannot tell you.
Before deciding scope or bringing questions to the author:
docs/latest/ and include/ for the feature name, related component names, and obvious synonymsupdating-migrating/what-is-new.md for recent entries about the same area โ they show how similar changes were framedTwo kinds of questions, only one belongs to the author:
| Find in the repo (do not ask) | Ask the author |
|---|---|
| Where a feature lives in the navigation | Subscription tier / availability for unreleased features |
| Relationships between existing features | Official naming, UI labels, parameter names โ especially for new functionality |
| Current behaviour, current terminology | User-visible framing (what does the user actually see or do differently?) |
| Which pages describe a subject | Form-factor scope (NGINX Node, Native Node, sidecar, ingress, OOB โ which apply?) |
| Existing config parameters, existing metrics | Version applicability, including backports |
| Style and formatting conventions | Migration / breaking changes โ what users need to do |
| Adjacent features that touch this change but were not mentioned |
After investigating, expect to find things the author did not mention. Bring them back rather than silently resolving:
<file> in the context of Y โ does this change apply there too?"Batch related questions. Prefer multi-option questions with concrete choices over open-ended ones. Asking is a working tool, not a sign that something went wrong.
Read the source material โ identify the user-visible change, the affected feature(s), and any UI/API/config names that will need to appear verbatim in docs.
Read reference files (declared in CLAUDE.md):
.doc-agent/glossary.md โ approved terminology.doc-agent/style-guide.md โ writing conventions.doc-agent/markdown-guide.md โ formatting conventionsDetermine the type of change:
| Type | Signs | Typical scope |
|---|---|---|
| New feature | Capability did not exist before | New page + updates to overview/setup/related pages |
| Changed functionality | Existing feature redesigned, new API/UI/config | Rewrite or extend existing pages, possibly add/remove pages |
| Fix | Something is wrong or missing in current docs | Targeted edits to 1-3 files |
| Removal | Feature/product discontinued; "remove all docs for X", "purge X from the site" | Delete pages, wrappers, nav entries, related sections, images across all versions โ see "Removal across versions" below |
Find all affected pages: grep for the feature name, key terms, and related concepts across docs/latest/ and include/. List every hit, including ones that look unrelated โ read the surrounding paragraphs before dismissing.
For removal tasks, broaden the grep to cover every version dir from the start:
grep -rln "<feature-term>" docs/ include/ mkdocs-*.yml
Version wrappers live under docs/{5.0,6.x,7.x}/.
Read each affected page fully before making changes.
Surface discrepancies to the author. If the repo describes the feature differently from the author's description, if two existing pages contradict each other, or if you found related areas the author did not mention โ raise them now, before scoping further.
For each affected page, determine what to do:
| Action | When |
|---|---|
| Create new page | New concept, standalone workflow, enough content for a full article |
| Rewrite | Page structure fundamentally changes due to redesign |
| Extend | Add sections, table rows, list items, tabs for new capability |
| Update | Change specific values: versions, parameter names, UI paths |
| Fix | Correct factual errors, broken links, terminology, style |
| Delete/merge | Rework consolidates features โ remove page, update nav, fix inbound links |
If creating new pages, determine:
mcp-discovery.md, auth-flows.md)New pages: write following the structure of existing pages in the same section. Typical structure:
# Feature name <subscription-badge-if-needed>
<1-3 sentence intro>
## Requirements
## How <feature> works
## <Feature-specific sections>
Adapt to the feature โ not every page needs all sections. Before writing, open 1-2 sibling pages in the same folder and match their structure (intro length, section order, presence of "Use cases" / "Limitations" / "Troubleshooting").
Existing pages: match the formatting patterns already in the page (same table style, admonition style, list format). For fixes, make the minimal change needed.
Cross-references: if a page was renamed or an anchor changed, grep for all references and update them. Add links from overview/landing pages to new content.
Screenshots: if UI changed, replace image references or add <!-- TODO: update screenshot -->. Place new images in root images/ directory.
If new pages were created:
mkdocs-*.yml configs at the repo root (e.g., mkdocs-6.x.yml, mkdocs-7.x.yml); each one corresponds to a docs/<X>/ directorydocs/<X>/ create a wrapper at the matching path with content: --8<-- "latest/<path>"mkdocs-*.ymlIf a new customer-facing capability was added (a feature, not just a config tweak or a bug fix), audit docs/latest/about-wallarm/subscription-plans.md. The table lists features per subscription tier and needs a new row when a new capability ships. Procedure:
subscription-plans.md and find the matching section header (Real-time protection, API protocol support, Security posture, Security testing, Additional options). Place the new row next to its closest parent feature so related rows cluster.Yes for tiers that include the capability, No for tiers that do not.If pages were renamed or deleted:
_redirects (the active root version's _redirects, plus the next-root's)Removal across versions. When the request is "remove all documentation for X from the site" (typically a discontinued product/feature), the cleanup must reach every version, not just docs/latest/. Touch all of the following:
| Surface | Files |
|---|---|
| Sources | docs/latest/<paths> |
| Version dirs | docs/{5.0,6.x,7.x}/<paths> (wrappers or frozen full copies โ check) |
| mkdocs nav | mkdocs-*.yml for every active version (e.g., mkdocs-6.x.yml, mkdocs-7.x.yml) |
| Shared includes | include/<files> |
| Redirects | docs/{5.0,6.x,7.x}/_redirects (only those that exist; the root version is the main one) |
| Images | images/<paths> (single shared source; remove only if no surviving page references them) |
| Auto-generated LLM indexes | docs/{6.x,7.x}/llms.md and llms.txt โ pruning is optional (they regenerate), but cleaner to scrub in the same PR |
Watch for frozen full copies in older version dirs: when a version stops being root, version-specific pages get copied from docs/latest/ into that older version dir as full files (instead of --8<-- "latest/..." wrappers). For removals, these frozen copies must be edited directly โ they will not follow updates to docs/latest/. Verify each affected path in each version dir individually:
for v in 5.0 6.x 7.x; do
head -1 "docs/$v/<path-to-affected-file>" 2>/dev/null | grep -q "8<--" \
&& echo "$v: wrapper" || echo "$v: FULL โ needs direct edit"
done
Update related pages: overview/landing pages always. Add an entry to updating-migrating/what-is-new.md only if this is a user-visible capability or behavior change โ skip it for fixes, terminology updates, internal restructuring, and screenshot refreshes.
Run these checks before handing off:
Inbound references resolve. If anything was renamed, deleted, or moved:
grep -rn "<old-page-name>\|<old-anchor>" docs/latest/ include/
Expect zero results outside changelog/history sections. Repeat across every active docs/<X>/ directory.
New pages render. Run ./serve.sh mkdocs-<root>.yml (and any other active version config) and open the new/edited page. Confirm: title renders, admonitions render, code blocks render, images load, internal links resolve.
New pages are wired up. For every new page in docs/latest/, check that a wrapper exists at the matching path in every active docs/<X>/, and that the page is in nav of every mkdocs-*.yml.
Terminology and style. Cross-check feature/product names against .doc-agent/glossary.md. Cross-check formatting (lists, admonitions, code fences, links) against .doc-agent/markdown-guide.md and .doc-agent/style-guide.md.
These come from repeated review-and-rewrite cycles on real PRs. Apply during Phase 3 (Execute) and during self-review before handoff โ they prevent a class of rewrites the author would otherwise drive. They sit on top of .doc-agent/style-guide.md, which covers sentence-level conventions; this section covers paragraph-, section-, and article-level choices.
When a screenshot, table, or wizard accompanies a section, the prose should explain what the section is for and what decisions the user makes there. It should not enumerate every column, field, or button visible in the image โ those are self-evident. A two-sentence description ("Use this tab to create recurring scans and review their history") beats a four-bullet enumeration of column headers when both convey the same information. Reserve bold formatting for the few UI elements the user actually interacts with (buttons they click, fields where the value matters), not every visible label.
Inside a numbered step sequence, "click Next" and "click Add Account" at the end of every step carry no information โ they describe inevitable UI mechanics, not decisions. Document the configuration choices (which option is selected, what value is entered, what file is uploaded) and let the obvious clicks remain implicit. "Set X, click Next, then set Y, click Next, then Z, click Add" reduces to "Configure X, Y, and Z" with the field-level guidance.
When documenting a Console section with tabs or sub-tabs, structure the article to match: top-level tabs become ## headings, sub-tabs become ### headings, in the same order the user sees them. Do not invent abstract categories that mix items the UI presents separately, and do not split items the UI presents together into different pages. A reader reading the docs side-by-side with the product should see the same hierarchy in both.
Bullets fit parallel, discrete, non-overlapping items: a list of mutually exclusive actions, a set of supported services, a checklist of prerequisites. Explanation of a concept or a process belongs in a paragraph. If a bullet item is more than one sentence, or if bullets re-introduce the same subject each time ("Each finding shows: severity โ ...; status โ ...; source โ ..."), prose is the better fit. Keep paragraphs short โ one idea each, split when stuffing more than two or three.
"Remediation recommendation" โ "how to fix it". "Surface the IAM principal" โ "show who created it". "Resource configuration analysis" โ "checks for risky setups". When a shorter, more concrete phrasing conveys the same meaning, prefer it. Avoid abstraction nouns ("attribution", "enrichment", "aggregation") in favor of verbs and concrete nouns where possible.
When a term like "finding", "policy", "rule", or "drift" appears as a section heading or anchor concept, the first paragraph should define it inline โ even if it is defined elsewhere. Readers land on pages from search and external links, not always via the overview. Do not assume the reader has read prior sections.
AWS Marketplace listings, blog posts, sales decks, and adjacent products' changelogs may claim capabilities the product does not have, list services it does not yet cover, or describe authentication methods that work only in dev. Source of truth: the IAM policy template, the actual collectors directory, the product's own changelog, the routes in API handlers. If a claim cannot be traced to code, raise it with the author rather than transcribing it.
For setup that involves a third-party product (AWS, Azure, GCP, Postman, etc.), link to that product's own documentation rather than reproducing its UI workflow. State the intent โ "create an IAM user, attach the policy, generate access keys" โ and link each phrase to the corresponding vendor docs page. Their UI changes; their docs follow; ours do not. Less to maintain.
When directing the reader to a value in a third-party UI, name the exact location: tab, page, or section. "See the stack outputs" is not enough; "once the status changes to CREATE_COMPLETE, open the Outputs tab on the stack page and copy the DiscoveryRoleArn value" is.
When describing a feature that involves lookups, scans, or computation, be explicit about when it happens โ on every scan, on user request, once at setup, daily, etc. "Infrastructure Discovery queries CloudTrail" reads as automatic and per-asset. "When you open an asset, Infrastructure Discovery queries CloudTrail" makes it clear the lookup is lazy and on-demand. The reader's mental model of cost, latency, and behavior depends on this.
Pricing, plan-tier limits, feature-comparison tables, AWS region lists, third-party version-support matrices โ content maintained in another channel (marketplace listing, vendor docs, dynamic page) should be linked from our docs, not duplicated. Duplication drifts; the moment one side updates, the other lies. Link the source and write a short context sentence.
When section headings are renamed, reordered, or demoted/promoted, the slug-based anchor changes. Internal [text](#anchor) and external file.md#anchor links break silently โ the page still renders, the link does not jump where intended. After any restructure, grep for the old anchor name across docs/latest/ (and across version dirs for frozen full copies) and update every reference. Do this as a discrete pass, not interleaved with other edits.
If two list items describe the same product mechanism through different framings ("Exposure detection" + "Security posture analysis", both implemented by the same built-in rule engine), they are not two features โ they are one feature described twice. Merge them. The marketplace may split them into separate marketing pillars; docs follow product reality, not marketing framing.
"The Findings sub-tab is the primary place to review findings. Each finding shows..." โ the first sentence is preamble. Open with substantive content. The reader already knows they are reading the Findings section; they do not need to be told that the Findings section is about findings.
New capability added to an existing feature. Updated 6 existing pages (overview, exploring, risk-score, sensitive-data, setup, agentic-ai-discovery), created 2 new pages (mcp-discovery, mcp-sessions), updated overview page.
Complete rewrite of azure-sentinel.md (~60 โ ~500 lines) when the product switched APIs. Same filename preserved, 6 new screenshots, cross-links updated.
Started as a single page, evolved through: draft โ review rewrite โ companion page added โ overview created โ integration with Node documented.
Smaller-scope: parameter names changed, UI screenshots outdated, new options added. Usually 1-3 files, not full rewrites.
Whole product line retired. Required deleting source pages in docs/latest/installation/on-premise/, wrappers in every version dir (5.0/, 6.x/, 7.x/), removing nav entries from the mkdocs configs, pruning the "On-Premise" item from include/deployment-forms.md, removing the dedicated ## On-Premise section from shared-responsibility.md, rewriting generic mentions of "on-premise" to "self-hosted", removing the "On-Premise" card from installation/supported-deployment-options.md in 6.x/7.x/5.0, deleting the on-premise images, adding redirects from the deleted URLs to installation/supported-deployment-options/ in each _redirects file, and scrubbing the On-Premise entries from llms.md / llms.txt. ~30+ files touched. The acceptance criterion was URL inaccessibility across every version.
mkdocs-*.yml, inbound links from overview/landing pages โ they must all land in the same PR_redirects and fixing every inbound cross-referencewhat-is-new.md for fixes, terminology, or internal restructuring โ reserve it for user-visible capability or behavior changesdocs/latest/ โ the version dirs (docs/{5.0,6.x,7.x}/, wrappers or frozen full copies) and every mkdocs-*.yml nav must be cleaned in the same PR, or the discontinued content stays publicly accessible at versioned URLs.