docs: add write-feature-docs skill for documenting abs features - #281
Conversation
Orchestrator skill that turns an ABsmartly feature into Docusaurus Product Documentation pages: research (via the abs document-feature-capture skill) → confirm framing → write pages matching site conventions → screenshots → validate. Captures the Docusaurus conventions, the <Image> component usage, anchor/link rules, and the dev-server validation loop (incl. the known cytoscape/mermaid build quirk to ignore). Content + validation only; leaves worktree/JIRA/PR to start-feature.
✅ Deploy Preview for absmartly-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughAdds the Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
.claude/skills/write-feature-docs/references/validation.md (1)
9-12: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMake the dependency symlink example portable.
The hardcoded
/Users/<you>/...path fails outside macOS and requires manual editing. Prefer$HOME/git_tree/docs/node_modules, or explicitly mark the path as a platform-specific placeholder.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/write-feature-docs/references/validation.md around lines 9 - 12, Update the dependency symlink example in the validation documentation to use the portable $HOME/git_tree/docs/node_modules path instead of the hardcoded /Users/<you>/ path, while preserving the command’s worktree context and behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/write-feature-docs/references/validation.md:
- Around line 40-55: Update the validation guidance around the Playwright checks
to enumerate every changed MDX route and run the anchor, link, and image
validations against each route rather than a single <area>/<page>. Ensure the
procedure reports failures per page and only passes when all changed pages have
valid anchors, links, and loaded images.
- Around line 30-31: Update the “Pages compile” validation procedure to avoid
treating HTTP 200 responses as proof of successful compilation. Require checking
dev-server error overlays and logs, failing on unrecognized MDX or compile
errors, while whitelisting only the documented Cytoscape/Mermaid issue; apply
the same criteria to the related validation steps around the referenced section.
- Around line 20-25: Update the readiness-check loop in the development server
validation procedure to track whether a 200 response was received; after all 15
attempts fail, exit with status 1 so subsequent validation does not run without
a ready server.
In @.claude/skills/write-feature-docs/SKILL.md:
- Around line 25-27: Add a suitable language identifier, preferably text, to the
fenced workflow diagram in .claude/skills/write-feature-docs/SKILL.md lines
25-27 and the production-build error fence in
.claude/skills/write-feature-docs/references/validation.md lines 63-65; no other
content changes are needed.
---
Nitpick comments:
In @.claude/skills/write-feature-docs/references/validation.md:
- Around line 9-12: Update the dependency symlink example in the validation
documentation to use the portable $HOME/git_tree/docs/node_modules path instead
of the hardcoded /Users/<you>/ path, while preserving the command’s worktree
context and behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b7dabfc3-a14c-4593-8905-a7ec210096f9
📒 Files selected for processing (3)
.claude/skills/write-feature-docs/SKILL.md.claude/skills/write-feature-docs/references/docusaurus-conventions.md.claude/skills/write-feature-docs/references/validation.md
| yarn start --port 3111 --no-open > /tmp/docs-dev.log 2>&1 & | ||
| # wait for readiness: | ||
| for i in $(seq 1 15); do | ||
| curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3111/docs/web-console-docs/<area>/<page> | grep -q 200 && { echo READY; break; } | ||
| sleep 5 | ||
| done |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Fail when the dev server never becomes ready.
After 15 unsuccessful attempts, the loop exits successfully and the procedure continues without a running server. Track readiness and exit 1 after the timeout so validation cannot proceed against an unavailable server.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/write-feature-docs/references/validation.md around lines 20 -
25, Update the readiness-check loop in the development server validation
procedure to track whether a 200 response was received; after all 15 attempts
fail, exit with status 1 so subsequent validation does not run without a ready
server.
| ### 1. Pages compile (no MDX errors) | ||
| If an `.mdx` page has a syntax error, the dev server logs it and the page won't load. A clean start + HTTP 200 on your pages = compiled. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Do not treat HTTP 200 as proof of compilation.
The procedure itself notes that the dev server can show a red error overlay while still serving pages, so a 200 response can coexist with MDX or compile errors. Fail on unrecognised error overlays/log entries and whitelist only the documented cytoscape/mermaid issue.
Also applies to: 59-71
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/write-feature-docs/references/validation.md around lines 30 -
31, Update the “Pages compile” validation procedure to avoid treating HTTP 200
responses as proof of successful compilation. Require checking dev-server error
overlays and logs, failing on unrecognized MDX or compile errors, while
whitelisting only the documented Cytoscape/Mermaid issue; apply the same
criteria to the related validation steps around the referenced section.
| To positively confirm an anchor exists (client-rendered, so use a JS-capable check rather than curl+grep): | ||
|
|
||
| ```js | ||
| // via a standalone Playwright script (see the abs skill's app-bring-up.md for resolving playwright) | ||
| await page.goto('http://localhost:3111/docs/web-console-docs/<area>/<page>', { waitUntil: 'networkidle' }); | ||
| const ok = await page.evaluate(() => !!document.getElementById('<expected-anchor-slug>')); | ||
| ``` | ||
|
|
||
| ### 3. Images load | ||
| Confirm every `<Image>` resolves (no missing file / `naturalWidth === 0`): | ||
|
|
||
| ```js | ||
| const broken = await page.evaluate(() => | ||
| Array.from(document.querySelectorAll('article img')).filter(i => i.complete && i.naturalWidth === 0).length); | ||
| console.log('broken images:', broken); // expect 0 | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
Validate every changed page, not one route.
The examples check only one <area>/<page>, one expected anchor, and images in the currently loaded document. A feature spanning multiple pages can therefore pass while another page has broken links, anchors, or images. Enumerate all changed MDX routes and validate each page.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/write-feature-docs/references/validation.md around lines 40 -
55, Update the validation guidance around the Playwright checks to enumerate
every changed MDX route and run the anchor, link, and image validations against
each route rather than a single <area>/<page>. Ensure the procedure reports
failures per page and only passes when all changed pages have valid anchors,
links, and loaded images.
| ``` | ||
| Research → Confirm framing → Write pages → Screenshots → Validate | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add languages to both fenced blocks.
.claude/skills/write-feature-docs/SKILL.md#L25-L27: addtext(or another suitable language) to the workflow diagram fence..claude/skills/write-feature-docs/references/validation.md#L63-L65: addtextto the production-build error fence.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 25-25: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
📍 Affects 2 files
.claude/skills/write-feature-docs/SKILL.md#L25-L27(this comment).claude/skills/write-feature-docs/references/validation.md#L63-L65
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/write-feature-docs/SKILL.md around lines 25 - 27, Add a
suitable language identifier, preferably text, to the fenced workflow diagram in
.claude/skills/write-feature-docs/SKILL.md lines 25-27 and the production-build
error fence in .claude/skills/write-feature-docs/references/validation.md lines
63-65; no other content changes are needed.
Source: Linters/SAST tools
1 participant
Summary
Adds
write-feature-docs, a skill that turns an ABsmartly feature into Docusaurus Product Documentation pages — capturing the workflow we used to document Warehouse Native (Fully vs Hybrid) so it's repeatable instead of trapped in a transcript.It's the orchestrator half of a two-skill pair. Its companion,
document-feature-capture, lives in the abs repo (separate PR) and handles codebase research + screenshots; this skill auto-invokes it.What it does
Single entry point (
/write-feature-docs <feature>) running five phases:document-feature-capture(research mode) → a structured report that flags product-judgment calls the code can't settle.AskUserQuestionbefore writing. Strongly recommended, not hard-blocking..mdxmatching site conventions.document-feature-capture(capture mode); degrades gracefully to "pages + list of owed screenshots" if the app can't be brought up.Files
Provenance / accuracy
Every convention and command is drawn from the actual Warehouse Native docs session and verified against this repo (the
<Image>import-depth rule, anchor slugging, the cytoscape/mermaid build error being pre-existing and unrelated). Content rules encode the corrections the product owner made during that session: mirror the product's own labels, say "can" not "must" where the product allows a choice, and don't leak internal implementation.Notes
start-feature, which can call this as its implementation step.feat/document-feature-capture-skillon absmartly/abs.Companion PR: absmartly/abs#4624 — the
document-feature-captureskill this one delegates to.Summary by CodeRabbit