[ENG-1502] Create Agent SKILLS to auto-update documentations once a feature is finished (#890)

trangdoan982 · devin-ai-integration[bot] · graphite-app[bot] · web-flow · commit 06181bf70b11 · 2026-03-23T08:26:01.000-07:00
* create skill * Update skills/update-docs.md Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com> * format * address PR comments * update * Update skills/update-user-docs/references/navigation-mapping.md Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> * format * Apply suggestion from @graphite-app[bot] Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> * Update .gitignore Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com> * DRY the contributing.md * remove files --------- Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com>
diff --git a/.gitignore b/.gitignore
@@ -40,4 +40,4 @@ local/*
 .cursor/debug.log
 apps/tldraw-sync-worker/tsconfig.tsbuildinfo
 apps/tldraw-sync-worker/.wrangler/*
-.claude/*
+.claude/*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -47,15 +47,11 @@ Blog posts are located in `/apps/website/app/(home)/blog/posts/`
 
 ### Plugin Documentation
 
-Plugin documentation is organized in `/apps/website/app/(docs)/docs/` with separate folders:
+Detailed guidance for plugin docs lives next to the update-user-docs skill:
 
-- `/obsidian/pages/` - Obsidian plugin documentation
-- `/roam/pages/` - Roam Research extension documentation
-- `/sharedPages/` - Documentation shared between platforms
-
-1. **Create your documentation file**: Add a new `.md` file in the appropriate platform's `pages/` folder
-2. **Use standard Markdown**: No special frontmatter is required for documentation files
-3. **Update navigation**: You may need to update the corresponding `navigation.ts` file to include your new page in the sidebar
+- **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** — where files live, `docMap.ts` (shared pages), and `navigation.ts` (every new page)
+- **[doc-conventions.md](./skills/update-user-docs/references/doc-conventions.md)** — filenames, frontmatter, screenshots, and cross-links
+- **[scope-detection.md](./skills/update-user-docs/references/scope-detection.md)** — how changed file paths map to Obsidian vs Roam vs shared docs (useful when unsure where a doc belongs)
 
 ### Documentation Images
 
diff --git a/skills/update-user-docs/SKILL.md b/skills/update-user-docs/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: update-user-docs
+description: Auto-update user-facing documentation when a feature or behavior change ships. Run when dev invokes manually so they can add the doc to a PR ready-for-review. Optionally pass a PR number for an already-merged PR.
+metadata:
+  argument-hint: "[PR number]"
+---
+
+# Update Docs
+
+Auto-update user-facing documentation when a feature or behavior change ships.
+If `$ARGUMENTS` is provided, treat it as a GitHub PR number. Use `gh pr view $ARGUMENTS` to get the PR diff, changed files, and description. Use this instead of the current branch context.
+
+If no argument is provided, use the current branch's diff against main, commit messages, and any linked Linear ticket to determine what changed.
+
+## When to Run
+
+On demand. Two modes:
+
+- **Current branch** — Run while on a feature branch that's ready for PR or review.
+- **Merged PR** — Pass a PR number to generate docs for an already-merged PR that's missing documentation.
+
+## Step 1: Gather Context
+
+### If running for the current branch
+
+Collect information from three sources:
+
+1. **Changed files** — Run `git diff main...HEAD --name-only` to identify what changed. Use file paths to determine the affected platform (see [scope-detection.md](references/scope-detection.md) for mapping).
+2. **Commit messages** — Run `git log main...HEAD --oneline` for a summary of what was done.
+3. **Linear ticket** — If a Linear ticket is linked (branch name or PR description), pull the title, description, and acceptance criteria for additional context. Use Linear MCP if available. If it's not available, prompt the dev to install Linear MCP using these instructions: https://linear.app/docs/mcp
+
+### If running for a merged PR
+
+Use the PR number to gather context via `gh`:
+
+1. **PR details** — Run `gh pr view <PR_NUMBER>` to get the title, description, and linked issues.
+2. **Changed files** — Run `gh pr diff <PR_NUMBER> --name-only` to identify what changed. Use file paths to determine the affected platform.
+3. **Linear ticket** — If a Linear ticket is referenced in the PR title, branch name, or description, pull additional context from it.
+
+## Step 2: Determine If Docs Are Needed
+
+Apply the scope detection heuristic. See [scope-detection.md](references/scope-detection.md) for the full yes/no lists and file path → platform mapping.
+
+If no docs update is needed, inform the dev and stop.
+
+## Step 3: New Page vs Update Existing
+
+1. Search existing documentation for content related to the change. See [doc-conventions.md](references/doc-conventions.md) for file locations.
+2. **Ask the dev:** "I found these existing pages that might be related: [list]. Should I update one of these, or create a new page?"
+3. Defaults:
+   - Completely new feature with no existing coverage → new page
+   - Extending or modifying an already-documented feature → update existing page
+
+## Step 4: Write or Update the Doc
+
+Follow the formatting rules in [doc-conventions.md](references/doc-conventions.md) (frontmatter, filenames, screenshot placeholders, cross-link integrity, side observations).
+
+If a **new page** is created, register it in navigation. See [navigation-mapping.md](references/navigation-mapping.md) for `docMap.ts` and `navigation.ts` patterns and examples.
+
+## Step 5: Verification
+
+1. Present the draft changes to the dev for review.
+2. List any screenshot placeholders that need filling.
+3. Flag any broken cross-links or stale content observed.
+4. **Leave all changes as unstaged modifications** — do not commit. The dev reviews and commits themselves.
diff --git a/skills/update-user-docs/references/doc-conventions.md b/skills/update-user-docs/references/doc-conventions.md
@@ -0,0 +1,49 @@
+# Documentation Conventions
+
+## File Locations
+
+Platform-specific docs live in their respective directories:
+
+- **Obsidian:** `apps/website/app/(docs)/docs/obsidian/pages/`
+- **Roam:** `apps/website/app/(docs)/docs/roam/pages/`
+- **Shared (cross-platform):** `apps/website/app/(docs)/docs/sharedPages/`
+
+Only place docs in `sharedPages/` if the content applies identically to both platforms and is explicitly specified as shared.
+
+## Filename Convention
+
+Use **kebab-case** for all doc filenames (e.g., `creating-discourse-nodes.md`).
+
+## Frontmatter
+
+Every doc file **must** include this frontmatter block:
+
+```yaml
+---
+title: "Page Title"
+date: "YYYY-MM-DD"
+author: ""
+published: true
+---
+```
+
+## Screenshot Placeholders
+
+For UI changes or new features with visual elements, insert a placeholder:
+
+```markdown
+<!-- TODO: Add screenshot of [describe the UI element or feature] -->
+
+![Screenshot placeholder](placeholder)
+```
+
+Always inform the dev that there are screenshot placeholders to fill in.
+
+## Cross-Link Integrity
+
+- When adding or updating cross-links (e.g., `[text](./other-page)`), verify that the target page exists.
+- If a link target does not exist, flag it to the dev.
+
+## Side Observations
+
+If while editing an existing doc you notice stale or incorrect content unrelated to the current change, flag it as a side observation to the dev. Do not silently fix unrelated content.
diff --git a/skills/update-user-docs/references/navigation-mapping.md b/skills/update-user-docs/references/navigation-mapping.md
@@ -0,0 +1,86 @@
+# Navigation Mapping
+
+When a **new page** is created, it must be registered in two places: `docMap.ts` (for shared pages) and `navigation.ts` (for all new pages).
+
+## docMap.ts — Slug-to-directory mapping
+
+Maps page slugs to their content directories. Platform-specific pages use the `default` path automatically, so you only need to add entries here for **shared pages**.
+
+### File locations
+
+- Obsidian: `apps/website/app/(docs)/docs/obsidian/docMap.ts`
+- Roam: `apps/website/app/(docs)/docs/roam/docMap.ts`
+- Shared: `apps/website/app/(docs)/docs/shared/docMap.ts`
+
+### How it works
+
+Each platform's `docMap.ts` spreads in `sharedDocMap` from the shared module. Platform-specific pages resolve via the `default` key.
+
+**Obsidian example:**
+
+```ts
+import { DocMapType, sharedDocMap } from "~/(docs)/docs/shared/docMap";
+
+const OBSIDIAN_DOCS = "app/(docs)/docs/obsidian/pages";
+
+export const docMap: DocMapType = {
+  default: OBSIDIAN_DOCS,
+  ...sharedDocMap,
+};
+```
+
+**Shared docMap (`apps/website/app/(docs)/docs/shared/docMap.ts`):**
+
+```ts
+export const SHARED_DOCS = "app/(docs)/docs/sharedPages";
+
+export const sharedDocMap = {
+  "what-is-a-discourse-graph": SHARED_DOCS,
+  "base-grammar": SHARED_DOCS,
+  "literature-reviewing": SHARED_DOCS,
+  "research-roadmapping": SHARED_DOCS,
+  "reading-clubs": SHARED_DOCS,
+  "lab-notebooks": SHARED_DOCS,
+} as const;
+```
+
+**When to update:** Only when adding a shared page. Add the slug → `SHARED_DOCS` mapping in `sharedDocMap`.
+
+## navigation.ts — Sidebar navigation
+
+Controls what appears in the docs sidebar. **Must be updated for every new page.**
+
+### File locations
+
+- Obsidian: `apps/website/app/(docs)/docs/obsidian/navigation.ts`
+- Roam: `apps/website/app/(docs)/docs/roam/navigation.ts`
+
+### Structure
+
+Navigation is an array of sections, each with a title and links:
+
+```ts
+import { NavigationList } from "~/components/Navigation";
+
+const ROOT = "/docs/obsidian";
+
+export const navigation: NavigationList = [
+  {
+    title: "🏠 Getting started",
+    links: [
+      { title: "Getting started", href: `${ROOT}/getting-started` },
+      { title: "Installation", href: `${ROOT}/installation` },
+    ],
+  },
+  {
+    title: "⚙️ Configuration",
+    links: [
+      { title: "Node types & templates", href: `${ROOT}/node-types-templates` },
+      { title: "Relationship types", href: `${ROOT}/relationship-types` },
+    ],
+  },
+  // ...more sections
+];
+```
+
+**To add a new page:** Insert a ``{ title: "Page Title", href: `${ROOT}/slug` }`` entry in the appropriate section's `links` array.
diff --git a/skills/update-user-docs/references/scope-detection.md b/skills/update-user-docs/references/scope-detection.md
@@ -0,0 +1,35 @@
+# Scope Detection
+
+## Heuristic: "Would a user notice this change?"
+
+Use this question to determine whether a code change requires a documentation update.
+
+## Update docs for
+
+- New user-facing feature
+- Changed behavior of an existing feature
+- Removed feature
+- New, changed, or removed settings/configuration
+- Changed setup or prerequisites
+- Deprecation of a feature (add a warning note, don't remove content)
+
+## Do NOT update docs for
+
+- Internal refactor with no user-visible change
+- Bug fix that restores already-documented behavior
+- Test-only changes
+- Dev tooling changes (CI, linting, build config)
+- Performance optimization with no user-facing behavior change
+
+If no docs update is needed, inform the dev and stop.
+
+## File Path to Platform Mapping
+
+Use changed file paths to determine which platform's docs are affected:
+
+| File path pattern | Platform | Doc directory                                                   |
+| ----------------- | -------- | --------------------------------------------------------------- |
+| `apps/obsidian/`  | Obsidian | `apps/website/app/(docs)/docs/obsidian/pages/`                  |
+| `apps/roam/`      | Roam     | `apps/website/app/(docs)/docs/roam/pages/`                      |
+| `packages/`       | Ask dev  | Could affect either or both platforms                           |
+| `apps/website/`   | Website  | Usually not user-facing docs (unless it's the docs site itself) |
