| name | marketing-docs-maintenance |
| description | Keep the Diolog marketing/feature documentation set in docs/marketing/ current when a feature ships, a Linear ticket lands, or an area goes stale. Use this skill whenever the user asks to update, sync, refresh, or maintain the marketing docs / feature guide / product docs / feature documentation — e.g. 'update the marketing docs for DIO-1234', 'document this feature in the feature guide', 'the inbox docs are out of date', 'sync the product docs with what shipped', 'add this to existing-features.md', 'keep the feature documentation current' — or after implementing/changing a user-facing feature when the docs should follow. It updates the four-file set per area (features-build/final/XX-*.md + existing-features.md section 2.XX for technical detail; features-build/plain/XX-*.md + product-feature-guide.md section XX for plain language), plus outbound-contact-surfaces.md when a new contact/sharing/delivery surface is added. Enforces the content standards (technical files carry component names / routes / GraphQL ops / exact copy and NO opinions; plain files carry zero technical terms, second person, sentence case, no em dashes, no emojis), the four-file consistency rule, the supersede-don't-accumulate currency rule, and the live-app > source > ticket source-of-truth hierarchy. The canonical in-repo guide is docs/marketing/MAINTENANCE.md — this skill operationalises it. Trigger even if the user doesn't say 'marketing docs' explicitly; any 'reflect this shipped feature in the documentation' request for docs/marketing qualifies. Use when this capability is needed. |
| metadata | {"author":"DiologIR"} |
Marketing Docs Maintenance (Diolog)
You maintain the Diolog marketing/feature documentation in `docs/marketing/`. When a feature ships or a Linear ticket lands, you bring the docs back into agreement with what the app actually does — editing the right area files, at the right detail level, with zero leakage between the technical and plain-language registers. The docs are a **record that follows the code**, never a specification that leads it.
Canonical source: docs/marketing/MAINTENANCE.md in the target repo is the authoritative guide. Read it first every run — it may have evolved since this skill was written. This skill operationalises it; if the two disagree, MAINTENANCE.md wins and you should mention the drift.
The documentation set
Five maintained surfaces under docs/marketing/:
| File | Audience | Detail level |
|---|
existing-features.md | Engineers, AI agents, technical reviewers | Full technical detail — component names, GraphQL ops, route paths, state models, field names, validation rules, exact error/toast copy |
features-build/final/XX-*.md | Same as above (per-area working source) | Full technical detail — one file per area (01–19) |
product-feature-guide.md | PMs, customers, non-technical stakeholders | Zero technical detail — plain English: what users see and do |
features-build/plain/XX-*.md | Same as above (per-area working source) | Zero technical detail — one file per area (01–19) |
outbound-contact-surfaces.md | Product/design | Medium structured inventory of contact-input methods, delivery channels, options per surface |
The final/ and plain/ per-area files are the working source; existing-features.md (section 2.XX) and product-feature-guide.md (section XX) are the assembled documents. Both members of each pair must agree.
Area map (01–19) — final/ and plain/ share this numbering
| # | Area | Covers |
|---|
| 01 | Auth | Login, sign-in, company picker, access denied |
| 02 | Dashboard | Home screen, quick tools, regulatory updates, key metrics |
| 03 | Chat | Conversations, agents, prompts, document picker, compliance canvas |
| 04 | Inbox | Smart inbox, conversations, reply composer, approval flow |
| 05 | Documents | Library, templates, editor, publishing, delivery metrics |
| 06 | Calendar | Setup wizard, live view, calendar settings |
| 07 | Disclosure | Disclosure consistency checker |
| 08 | Perception | Perception studies |
| 09 | Sentiment | Sentiment analyses |
| 10 | Social | Monitoring (Investors tab, Competitors tab) |
| 11 | Surveys | Survey creation, editor, publish, distribution, results |
| 12 | Workflows | Library, intro page, run detail, step types |
| 13 | Widgets | Admin studio, FAQ hub, embeddable widgets |
| 14 | Portals | Public and private investor portals |
| 15 | Settings | Settings modal (all 8 panes) |
| 16 | Profile | User profile page |
| 17 | Help | Help and support |
| 18 | Admin | Admin console |
| 19 | Cross-cutting | Behaviours spanning multiple areas |
Inputs & intake
Establish what changed and which area(s) it touches. If unclear, ask.
- A Linear ticket (the common case) — e.g.
DIO-4761. Read it via the Linear MCP (load mcp__linear__get_issue and mcp__linear__list_comments through ToolSearch). Read the description AND the comments, especially any implementation-complete comment — that describes what actually shipped (which may differ from what was requested).
- A described feature change with no ticket — work from the description + the live app + source.
- A "this area is stale" request — re-derive the area from the live app and source and reconcile.
Map the change to one or more areas (01–19). A change can span several areas (and area 19 captures cross-cutting behaviour).
Source-of-truth hierarchy
When sources conflict, trust in this order:
- Live app (what the browser actually shows) — ultimate authority.
- Source code (what the components render) — next authority.
- Implementation-complete comments on the Linear ticket — what was built.
- Ticket description — what was requested (may differ from what shipped).
- These docs — a record, not a spec; they follow the code.
The e2e test-plan files (apps/web/e2e/test-plan/*.md) are a separate, older source documenting an earlier build. Do not use them as the authority for what exists now; when they conflict with the marketing docs, the marketing docs are more current.
Verify against the live app where you can (dev login → target page) or by reading the rendering source; don't document from the ticket alone.
Update process
For each affected area, update four files (two pairs) — and a fifth when contact/outbound surfaces change:
features-build/final/XX-*.md (technical detail)existing-features.md → section 2.XX (technical detail; must agree with #1)features-build/plain/XX-*.md (plain language)product-feature-guide.md → section XX (plain language; must agree with #3)outbound-contact-surfaces.md — only if a new outbound / sharing / contact surface was added (record contact-input methods, delivery channels, options)
Steps:
- Read the ticket (description + comments).
- Identify affected area file(s).
- Read the current content in those files.
- Replace outdated content — do not append
UPDATE: blocks, changelog entries, or "as of DIO-xxxx" notes. The docs describe the present state only.
- Verify four-file consistency (technical pair agrees; plain pair agrees; counts and names match across pairs).
- Update
outbound-contact-surfaces.md if relevant.
When multiple areas are affected, you may fan out one sub-agent per area (via Agent) — but give each agent disjoint area files so they don't collide, and run the shared assembled documents (existing-features.md, product-feature-guide.md) edits carefully (each area edits a different section 2.XX / XX; if agents race on the same assembled file, serialise those section edits in a final pass). Use TaskCreate/TaskUpdate to track areas.
Content standards
Technical register — existing-features.md + final/*.md
Include: component names (e.g. CompanyProfileForm, DocumentPicker); route paths (e.g. /workflows/[id], ?settings=profile); GraphQL operation names (queries/mutations/subscriptions); field names and types; exact error/toast copy in quotes; validation rules (required fields, formats, limits); loading/empty/error states with exact copy; accessibility attributes (roles, aria labels); permission model (which guards, which roles); state machines (status enums, transitions); known behaviours and bugs (with root cause when known).
Do NOT include: implementation advice or recommendations; inline source-code blocks; speculative future features; opinions on quality or design.
Structure per section: Overview (what it is, who uses it, where it lives) · Pages and routes table · Features (bulleted, grouped) · Interfaces (modals/drawers/panels/menus with field-level detail) · Interactions and logic (what happens on click/submit, sequencing) · States and validation · Permissions and visibility · Data and queryability (what durable records are produced, what the chat agent can answer) · Known behaviours.
Plain register — product-feature-guide.md + plain/*.md
Include: what the user sees (headings, buttons, lists, cards described visually); what happens when they interact (click, type, toggle, drag); what feedback they get (confirmations, warnings, errors in plain terms); empty/loading states in user terms; who can use it (roles in plain language); known quirks as user-observable behaviour.
Do NOT include: component names, file paths, route paths; GraphQL operations or API endpoints; field types, schema names, database details; technical root causes of bugs; accessibility attributes or aria labels; state-machine terminology; any word a non-developer would need to look up.
Style rules: second person ("you see", "you click"); say "pane/section/card/button/link", not "component/resolver/mutation"; describe errors as "a message appears saying…", not "renders an Alert with status=error"; no em dashes (use commas, full stops, or colons); no emojis; headings in sentence case.
Structure per section: Brief intro (what it is, who uses it, where it lives) · subsections by page or major feature · each subsection: Purpose · What you see · What you can do · States and feedback.
Quality checks (before a section is complete)
- Accuracy — matches the live app / source. Planned-but-unreleased features are clearly marked as such.
- Completeness — every interactive element, every state (loading/empty/error/success), every permission boundary.
- No leaks — technical files carry no opinions; plain files carry no code terms.
- Consistency — the same feature is described at the same scope across all four files. If the technical file says "6 segment options", the plain file also says 6.
- Currency — when a ticket supersedes an earlier one (e.g. DIO-4761 superseded DIO-4760 on workflows), the earlier description is replaced, not accumulated alongside.
Done criteria
- The affected area's four files are updated (plus
outbound-contact-surfaces.md if a contact/outbound surface changed).
- The technical pair agrees; the plain pair agrees; counts and names match across pairs.
- No
UPDATE:/changelog residue; outdated content replaced.
- No register leaks (no code terms in plain files; no opinions in technical files).
- Plain files obey the style rules (second person, sentence-case headings, no em dashes, no emojis).
- Documentation reflects what actually shipped per the source-of-truth hierarchy, not just the ticket request.
Example invocations
update the marketing docs for DIO-4761
the inbox approval flow changed — refresh the feature docs for area 04
document the new survey distribution surface in the product docs (and outbound-contact-surfaces.md)
sync existing-features.md and the plain guide with what shipped on workflows
Source: DiologIR/diolog-plugins — distributed by TomeVault.
