feat(slides): improve slide planning and validation guidance

[ethan-zhx]

Summary

Improve the lark-slides skill guidance around slide planning, asset planning, visual planning, troubleshooting, and validation. This also narrows the former layout lint tool into an XML/text-overlap preflight check so its name matches its actual scope.

Changes

• Add dedicated planning, visual planning, asset planning, troubleshooting, and validation references for lark-slides workflows.
• Streamline the main lark-slides skill instructions to point to the new workflow references.
• Rename layout_lint to xml_text_overlap_lint and update docs/tests to describe the reduced XML well-formed + text overlap scope.

Test Plan

• Unit tests pass: cd skills/lark-slides/scripts && python3 -m unittest xml_text_overlap_lint_test.py
• Manual local verification confirms the lark xxx command works as expected

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Rewrote and formalized slide creation workflow; added planning, visual, asset, template, troubleshooting, and validation guides
  • Added a Quick Reference decision table and explicit pre-/post-creation checklist with required plan artifacts and verification steps
• Tests
  • Updated lint test suite to match new text-overlap validation behavior and added template coverage tests
• Chores
  • Ignore local slide plan directory in repository ignore rules

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f58cc67b-d5bc-4809-bf58-c3eb93aa9e1a

📥 Commits

Reviewing files that changed from the base of the PR and between 65aff94 and 09e986d.

📒 Files selected for processing (11)

• .gitignore
• skills/lark-slides/SKILL.md
• skills/lark-slides/references/asset-planning.md
• skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
• skills/lark-slides/references/planning-layer.md
• skills/lark-slides/references/template-catalog.md
• skills/lark-slides/references/troubleshooting.md
• skills/lark-slides/references/validation-checklist.md
• skills/lark-slides/references/visual-planning.md
• skills/lark-slides/scripts/xml_text_overlap_lint.py
• skills/lark-slides/scripts/xml_text_overlap_lint_test.py

💤 Files with no reviewable changes (1)

• skills/lark-slides/references/template-catalog.md

✅ Files skipped from review due to trivial changes (4)

• .gitignore
• skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
• skills/lark-slides/references/troubleshooting.md
• skills/lark-slides/references/planning-layer.md

🚧 Files skipped from review as they are similar to previous changes (4)

• skills/lark-slides/references/validation-checklist.md
• skills/lark-slides/SKILL.md
• skills/lark-slides/scripts/xml_text_overlap_lint.py
• skills/lark-slides/scripts/xml_text_overlap_lint_test.py

---

📝 Walkthrough

Walkthrough

This PR reorganizes the lark-slides skill documentation around a planning-first workflow, introduces comprehensive specifications for planning layers, visual constraints, asset handling, and validation procedures, and refactors the layout-lint script to focus exclusively on text overlap detection.

Changes

Lark Slides Planning and Validation Framework

Layer / File(s)	Summary
SKILL.md restructure and core guidance skills/lark-slides/SKILL.md	Quick Reference decision table added; "CRITICAL" rules expanded to require reading auth/permissions, XML schema, and new planning/visual/asset/validation docs; "执行前必做" workflow checklist introduced with design principles and common mistakes; consolidated 4-step template/script procedure; wiki-link handling condensed to /wiki/TOKEN → wiki spaces get_node rule; shortcuts/API section rewritten emphasizing schema inspection before raw API calls; gradient rule and authoritative-schema note added.
Planning layer and visual/asset constraint specifications skills/lark-slides/references/planning-layer.md, skills/lark-slides/references/visual-planning.md, skills/lark-slides/references/asset-planning.md	New planning-layer.md defines mandatory slide_plan.json structure, plan-directory conventions, required fields (layout_type, text_density, visual_focus, asset_need), allowed layout vocabulary, and visual system planning. Visual-planning.md maps layout_type/visual_focus/text_density to concrete geometry and guardrails for a 960×540 canvas across multiple layout types. Asset-planning.md defines supported asset_type values, mandates fallback_if_missing with XML-native fallbacks, and specifies the plan→XML contract and examples.
Validation framework and reference doc cleanup skills/lark-slides/references/validation-checklist.md, skills/lark-slides/references/troubleshooting.md, skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md, skills/lark-slides/references/template-catalog.md, .gitignore	New validation-checklist.md mandates post-creation verification (record xml_presentation_id, xml_presentations.get, per-page checks) and requires automated XML text-overlap lint with summary.error_count == 0; troubleshooting.md adds XML preflight rules, ordered failure-handling, symptom→fix tables, and error-code mappings. Removed previous layout_lint.py preflight guidance from slide-create/template docs and added .lark-slides/ to .gitignore.
Lint script refactor from layout-lint to xml-text-overlap-lint skills/lark-slides/scripts/xml_text_overlap_lint.py, skills/lark-slides/scripts/xml_text_overlap_lint_test.py	xml_text_overlap_lint.py refocused to text-overlap detection only: exception type renamed LayoutLintError → XmlTextOverlapLintError, lint_slide signature simplified (no canvas size), should_flag_overlap simplified, and new helpers added (has_text_content, is_decorative_text, normalize_text_for_overlap, is_similar_text_overlay, estimate_text_line_count, estimate_text_visual_bbox, intersection_area, is_template_text_stack). Removed out-of-bounds/text-height/footer-collision checks. Tests renamed and updated to exercise new heuristics and add template-file coverage.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• larksuite/cli#516
• larksuite/cli#389
• larksuite/cli#684

Suggested labels

size/XL, documentation, lark-slides-skill, lint-tooling

Suggested reviewers

• fangshuyu-768
• kongenpei

🐰 A deck of slides takes shape with care,
Planning layers map each square with flair,
Visual motifs dance, assets align,
Text overlaps checked—validation divine!
From planning to lint, the workflow runs true, ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the main focus of the PR: improvements to slide planning and validation guidance in the lark-slides skill.
Description check	✅ Passed	The description is mostly complete and follows the template structure with Summary, Changes, and Test Plan sections, though manual verification checkbox remains unchecked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/slides_layout

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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 65.85%. Comparing base (b612dde) to head (09e986d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #847   +/-   ##
=======================================
  Coverage   65.85%   65.85%           
=======================================
  Files         517      517           
  Lines       48761    48761           
=======================================
  Hits        32113    32113           
  Misses      13885    13885           
  Partials     2763     2763           

☔ View full report in Codecov by Sentry.
📢 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@09e986d0fd4041e7c19ce9cce0969ced96b3a3aa

🧩 Skill update

npx skills add larksuite/cli#feat/slides_layout -y -g

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@skills/lark-slides/references/validation-checklist.md`:
- Line 10: Replace occurrences of the method-style notation
`xml_presentations.get` used in procedural text with the CLI form
`xml_presentations get` so documentation matches the actual bash examples;
search for instances of `xml_presentations.get` in the file and update the text
(e.g., the mentions around the validation checklist and any other paragraphs) to
use `xml_presentations get` consistently while leaving code blocks unchanged.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 95134680-1d42-406e-a177-0ae08a96507a

📥 Commits

Reviewing files that changed from the base of the PR and between b612dde and 65aff94.

📒 Files selected for processing (10)

• skills/lark-slides/SKILL.md
• skills/lark-slides/references/asset-planning.md
• skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md
• skills/lark-slides/references/planning-layer.md
• skills/lark-slides/references/template-catalog.md
• skills/lark-slides/references/troubleshooting.md
• skills/lark-slides/references/validation-checklist.md
• skills/lark-slides/references/visual-planning.md
• skills/lark-slides/scripts/xml_text_overlap_lint.py
• skills/lark-slides/scripts/xml_text_overlap_lint_test.py

💤 Files with no reviewable changes (1)

• skills/lark-slides/references/template-catalog.md