fix(contact): add actionable hint when fanout search all-fail with no API code

[Wang-Yeah623]

Summary

In shortcuts/contact/contact_search_user_fanout.go, when every fanout query fails AND the first failure has no Lark API code (transport / parse / panic / context-cancel), the returned ExitError was carrying an empty Hint. This is the only output.ErrWithHint call in shortcuts/ shipping an empty hint.

AGENTS.md is explicit on this:

every error message you write will be parsed by an AI to decide its next action. Make errors structured, actionable, and specific.

An empty hint gives the agent nothing to do.

Changes

• shortcuts/contact/contact_search_user_fanout.go: populate the hint on the no-API-code branch with the actionable next step — "retry the command; if it persists, narrow --queries to a single term to isolate the failing input". The other branch (with a real Lark code) already routes through output.ErrAPI and is unchanged.
• shortcuts/contact/contact_search_user_test.go: add TestFanoutAssemble_AllFailed_NoCode_HasActionableHint that asserts the returned *output.ExitError carries a non-empty Detail.Hint containing "retry". Confirmed it fails on main ("expected non-empty Hint so agents have a next step; got empty") and passes after the fix.

Test Plan

• go test ./shortcuts/contact/ -run TestFanoutAssemble — 6/6 sub-cases pass
• go test ./shortcuts/contact/ — full package passes
• Confirmed the new test fails on main (empty Hint) and passes with the fix
• go vet ./shortcuts/contact/, gofmt -l — clean
• No behaviour change for the existing branch with a Lark API code (output.ErrAPI)

Related Issues

• None

Summary by CodeRabbit

• Bug Fixes
  • Improved error messaging for contact search failures: when all queries fail without a structured error code, users now receive an actionable hint (retry and try narrowing the query).
• Tests
  • Added a regression test to verify the actionable hint is included in the error details when this failure scenario occurs.

[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: e19b4e52-60e7-4370-85f0-d755531767f7

📥 Commits

Reviewing files that changed from the base of the PR and between d36bd81 and 1f3b423.

📒 Files selected for processing (2)

• shortcuts/contact/contact_search_user_fanout.go
• shortcuts/contact/contact_search_user_test.go

---

📝 Walkthrough

Walkthrough

When all contact search fanout queries fail without a structured API error code, buildFanoutResponse now returns an error with an actionable hint directing users to retry the command or narrow --queries to isolate the failing input. A regression test validates this hint is present and non-empty.

Changes

Fanout error hint improvement

Layer / File(s)	Summary
Error hint implementation shortcuts/contact/contact_search_user_fanout.go	buildFanoutResponse updates the all-failed, no-code branch to return output.ErrWithHint with actionable guidance instead of an empty hint string.
Regression test for error hint shortcuts/contact/contact_search_user_test.go	Imports errors and output packages, then adds TestFanoutAssemble_AllFailed_NoCode_HasActionableHint to assert the error includes a non-empty hint containing "retry".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• larksuite/cli#707: Also modifies fanout failure handling in buildFanoutResponse and error detail messages.

Suggested labels

domain/contact

Suggested reviewers

• sang-neo03

Poem

🐰 A hint appears when queries fall,
Retry first, or narrow all,
Error messages, once bare and bleak,
Now guide users to solutions they seek! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding an actionable hint to error handling when fanout search fails with no API code.
Description check	✅ Passed	The PR description is well-structured, covers all template sections with concrete details, clearly explains the problem and solution, and documents comprehensive test verification.
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 unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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 67.76%. Comparing base (ce5b4f2) to head (1f3b423).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1054   +/-   ##
=======================================
  Coverage   67.76%   67.76%           
=======================================
  Files         590      590           
  Lines       55194    55195    +1     
=======================================
+ Hits        37400    37401    +1     
  Misses      14682    14682           
  Partials     3112     3112           

☔ 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@1f3b423d34130dc1c2cdba91b477459a4fdd6469

🧩 Skill update

npx skills add Wang-Yeah623/cli#fix/contact-fanout-empty-hint -y -g