feat: soften lark doc style guidance

[fangshuyu-768]

Summary

• Reframe lark-doc style guidance as optional expression components instead of mandatory formatting rules
• Remove fixed style targets such as default callout openings, rich-block density, mandatory section dividers, and default whiteboard-first behavior
• Keep XML, update workflow, and whiteboard technical constraints while letting the model follow user intent and existing document style

Validation

• git diff --check
• node scripts/skill-format-check/index.js skills
• bash scripts/check-doc-tokens.sh skills/lark-doc

Summary by CodeRabbit

• Documentation
  • Updated documentation workflow guidance to prioritize content and user goals over mandatory style requirements.
  • Refined whiteboard usage principles with clear criteria for when diagrams should be included.
  • Reframed formatting guidelines as optional component references rather than fixed style rules.
  • Clarified prerequisites for document creation and updates with conditional style reference guidance.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5f9a85f8-c4b0-46b0-9885-99490aa54f5e

📥 Commits

Reviewing files that changed from the base of the PR and between c0730b4 and bf7e7d1.

📒 Files selected for processing (7)

• skills/lark-doc/SKILL.md
• skills/lark-doc/references/lark-doc-create.md
• skills/lark-doc/references/lark-doc-update.md
• skills/lark-doc/references/lark-doc-whiteboard.md
• skills/lark-doc/references/style/lark-doc-create-workflow.md
• skills/lark-doc/references/style/lark-doc-style.md
• skills/lark-doc/references/style/lark-doc-update-workflow.md

---

📝 Walkthrough

Walkthrough

Across seven lark-doc skill documentation files, lark-doc-style.md is demoted from a mandatory prerequisite to an optional reference used only when rich blocks or beautification are explicitly needed. Whiteboard-by-default rules are replaced with intent-driven guidance, and workflow "Observe" steps are reframed around user-goal satisfaction rather than style compliance.

Changes

lark-doc Style Guide Demotion and Expression-Form Guidance Overhaul

Layer / File(s)	Summary
lark-doc-style.md rewritten as optional component reference skills/lark-doc/references/style/lark-doc-style.md	Document retitled from "文档样式指南" to "文档表达组件参考"; core principles, component-selection table, diagram-intent section, color semantics, layout rules, and quality checklist all changed from mandatory "must" framing to suggestion-based guidance.
Prerequisite lists updated across entry-point docs skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-create.md, skills/lark-doc/references/lark-doc-update.md	lark-doc-style.md removed from required-read lists and marked as a conditional reference only when rich blocks, beautification, or re-layout are requested; expression-form guidance added stating style follows user goals and content rather than a fixed enrichment target.
Whiteboard usage principles and Mermaid-vs-SVG rules refined skills/lark-doc/references/lark-doc-whiteboard.md	Added 画板使用原则 criteria distinguishing optional vs necessary board use and clarified the lark-doc/lark-whiteboard responsibility boundary; replaced blanket SVG preference with per-chart content/effect-based selection between Mermaid blocks and SVG SubAgent.
Create workflow Observe step and multi-wave process updated skills/lark-doc/references/style/lark-doc-create-workflow.md	Observe step reworded to check user-goal satisfaction; skeleton-creation and parallel-agent waves updated to provide lark-doc-style.md only when rich blocks are needed; polish wave redirected toward readability (table/grid/callout) rather than style metrics.
Update workflow Observe step and three-wave process updated skills/lark-doc/references/style/lark-doc-update-workflow.md	Observe step reframed around correctness and goal alignment; 第一波/第二波/第三波 evaluation and parallel-agent block rewriting updated to user-goal language; Agent 子任务要求 makes lark-doc-style.md conditional on rich-block or beautification needs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• larksuite/cli#1283: Updates SKILL.md and whiteboard routing guidance in the same lark-doc skill, directly overlapping with this PR's whiteboard scope boundary changes.
• larksuite/cli#1097: Changes lark-doc-whiteboard.md Mermaid-vs-SVG routing and whiteboard insertion workflow, the same section refined in this PR.
• larksuite/cli#901: Previously revised lark-doc-style.md, lark-doc-whiteboard.md, and the create/update workflow docs that this PR continues to adjust.

Suggested labels

size/M, domain/ccm

Suggested reviewers

• SunPeiYang996

Poem

🐇 Hop, hop — the rules grew soft today,
No more "must use whiteboard" come what may.
Style guides demoted, goals now lead the way,
Each callout and grid may or may not play.
The rabbit writes docs as the content sees fit —
Optional beauty, but never counterfeit! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch soften-lark-doc-style-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.35%. Comparing base (c0730b4) to head (bf7e7d1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1462   +/-   ##
=======================================
  Coverage   73.35%   73.35%           
=======================================
  Files         750      750           
  Lines       69250    69250           
=======================================
  Hits        50799    50799           
  Misses      14711    14711           
  Partials     3740     3740           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@bf7e7d1f6057cea99fe67410b1a16be658579e17

🧩 Skill update

npx skills add larksuite/cli#soften-lark-doc-style-guidance -y -g