feat(guides): rewrite in-product User Guides as Diátaxis how-tos #159

chihlasm · 2026-05-02T01:17:24Z

chihlasm commented

2026-05-02 01:17:24 +00:00

Summary

In-product /guides rewritten from 15 feature-dump guides → 43 problem-oriented Diátaxis how-tos under 10 categories.

Dropped 3 deprecated guides (Maintenance Flows, AI Assistant, Flow Assist Sparkles — those surfaces no longer exist post-FlowPilot pivot).
Renamed Step Library → Solutions Library throughout.
Corrected every "click X in the sidebar" reference to match live labels (Home, History, Tickets, Flows, Scripts, Data, Acct).
14 net-new how-tos for FlowPilot-era surfaces with no prior coverage: tasklane keyboard flow, view-what-we-know, ask-AI mid-session, pause-and-leave, resolve, record-fix-outcome, escalate, post-docs-to-ticket, send-client-update, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate.
Schema: added category and optional relatedSlugs to Guide; hub renders category sections (auto-hides empty); detail page renders a related-guides footer when set; card drops misleading "N sections" subtitle.
Fixed long-standing bug where **bold** markdown in step.tip rendered literally.

Test plan

tsc -b clean
Hub page renders 10 categories in order, only populated ones visible
All 43 detail pages render — smoke-tested every slug, no "Guide Not Found"
Tip markdown bolds correctly (/guides/start-a-session Tip block)
Sidebar labels in every guide match live UI (verified engineer login)
Owner-only guides verified against pro@ login: Membership inline form, Team Categories "Create Category" button, Chat Retention real labels ("Retention Period (days)", "Max Conversations", "Save Settings"), Integrations form fields
Pilot session header buttons (Resolve / Escalate / More session actions / Share Update / Pause) and Tasks panel structure (What we know · N, Questions, Diagnostic Checks, Send N of M Responses) verified live
Resolve / Escalate modal contents — deferred. Test session has 6 pending tasks gating Resolve; modals authored from project context, not live observation
change-teammate-role — dropped from scope. Test owner account has no non-owner members to inspect the role-change control. Re-add the guide once a teammate is invited and the control is verifiable

🤖 Generated with Claude Code

## Summary In-product `/guides` rewritten from 15 feature-dump guides → **43 problem-oriented Diátaxis how-tos** under 10 categories. - Dropped 3 deprecated guides (Maintenance Flows, AI Assistant, Flow Assist Sparkles — those surfaces no longer exist post-FlowPilot pivot). - Renamed Step Library → Solutions Library throughout. - Corrected every "click X in the sidebar" reference to match live labels (Home, History, Tickets, Flows, Scripts, Data, Acct). - 14 net-new how-tos for FlowPilot-era surfaces with no prior coverage: tasklane keyboard flow, view-what-we-know, ask-AI mid-session, pause-and-leave, resolve, record-fix-outcome, escalate, post-docs-to-ticket, send-client-update, build-script-from-scratch, open-suggested-flow, pin-a-flow, invite-teammate. - Schema: added `category` and optional `relatedSlugs` to `Guide`; hub renders category sections (auto-hides empty); detail page renders a related-guides footer when set; card drops misleading "N sections" subtitle. - Fixed long-standing bug where `**bold**` markdown in `step.tip` rendered literally. ## Test plan - [x] `tsc -b` clean - [x] Hub page renders 10 categories in order, only populated ones visible - [x] All 43 detail pages render — smoke-tested every slug, no "Guide Not Found" - [x] Tip markdown bolds correctly (`/guides/start-a-session` Tip block) - [x] Sidebar labels in every guide match live UI (verified engineer login) - [x] Owner-only guides verified against `pro@` login: Membership inline form, Team Categories "Create Category" button, Chat Retention real labels ("Retention Period (days)", "Max Conversations", "Save Settings"), Integrations form fields - [x] Pilot session header buttons (Resolve / Escalate / More session actions / Share Update / Pause) and Tasks panel structure (What we know · N, Questions, Diagnostic Checks, Send N of M Responses) verified live - [ ] Resolve / Escalate modal contents — deferred. Test session has 6 pending tasks gating Resolve; modals authored from project context, not live observation - [ ] `change-teammate-role` — dropped from scope. Test owner account has no non-owner members to inspect the role-change control. Re-add the guide once a teammate is invited and the control is verifiable 🤖 Generated with [Claude Code](https://claude.com/claude-code)

chihlasm added 1 commit 2026-05-02 01:17:24 +00:00

feat(guides): rewrite in-product User Guides as Diátaxis how-tos

Mirror to GitHub / mirror (push) Successful in 4s

Details

CI / frontend (pull_request) Successful in 4m57s

Details

CI / backend (pull_request) Successful in 10m21s

Details

CI / e2e (pull_request) Successful in 12m0s

Details

307a6285e6

Replace 15 feature-dump guides with 43 problem-oriented how-tos grouped
under 10 categories. Drop Maintenance Flows / AI Assistant / Flow Assist
Sparkles — those surfaces no longer exist post-FlowPilot pivot. Rename
Step Library → Solutions Library throughout. Correct every "click X in
the sidebar" reference to match live labels (Home, History, Tickets,
Flows, Scripts, Data, Acct).

Schema: add `category: CategoryId` and optional `relatedSlugs` to Guide;
new Category type and `categories` const drive hub ordering. GuidesHubPage
renders category sections (auto-hides empty); GuideDetailPage renders a
related-guides footer when set; GuideCard drops the misleading "N sections"
subtitle.

Fix step.tip markdown rendering — `**bold**` rendered literally because
tip used plain text instead of the same regex replacement used on
instruction.

14 net-new how-tos for FlowPilot-era surfaces with no prior coverage:
tasklane keyboard flow, view-what-we-know, ask-AI mid-session,
pause-and-leave, resolve, record-fix-outcome, escalate (Escalation
Mode), post-docs-to-ticket, send-client-update, build-script-from-scratch,
open-suggested-flow, pin-a-flow, invite-teammate.

Browser-verified against engineer + owner test users (sidebar labels,
account sub-pages, pilot-screen header buttons, Tasks panel, integration
form). tsc clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

chihlasm referenced this issue from a commit

2026-05-02 01:25:47 +00:00

docs(ai): mark guides rewrite as merged in handoff and current task

chihlasm added 1 commit 2026-05-02 01:25:47 +00:00

docs(ai): mark guides rewrite as merged in handoff and current task

Mirror to GitHub / mirror (push) Successful in 5s

Details

CI / frontend (pull_request) Successful in 5m1s

Details

CI / backend (pull_request) Successful in 13m8s

Details

CI / e2e (pull_request) Successful in 18m32s

Details

dc71d5873b

Update HANDOFF.md, CURRENT_TASK.md, and SESSION_LOG.md to reflect
that PR #159 is being merged into main, replacing the in-flight
"uncommitted" language with the merged-state rollup.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

chihlasm merged commit 93fa4eac5c into main

2026-05-02 02:19:53 +00:00

chihlasm referenced this issue from a commit

2026-05-02 02:19:55 +00:00

Merge pull request 'feat(guides): rewrite in-product User Guides as Diátaxis how-tos' (#159) from feat/guides-diataxis-rewrite into main

chihlasm referenced this issue from a commit

2026-05-08 02:56:10 +00:00

docs: refresh CURRENT-STATE, ROADMAP, README, DECISIONS for self-serve cutover

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: chihlasm/resolutionflow#159