fix(skill-nudge): log swallowed errors in debug mode

[stuart902]

What does this PR do?

Threads the existing global --debug flag into the skill-nudge pre-action context so the two remaining swallowed error paths in src/lib/skill-nudge.ts are diagnosable when debug output is requested.

Specifically:

• Profile lookup failures now emit a debug-only stderr diagnostic instead of disappearing silently.
• Managed-section target read failures (for example, an unreadable AGENTS.md) emit a debug-only stderr diagnostic while continuing to treat that target as absent.
• Non-debug behavior remains unchanged.
• JSON output remains unpolluted.
• Diagnostic delivery is itself best-effort, so a failing stderr/diagnostic sink cannot break the command.
• Regression tests cover both swallowed-error paths and the failure-isolation behavior.

This follows the debug-emission pattern established in #223.

Related issue

Closes #285

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that changes existing behavior)
• Documentation only
• Build / CI / chore

Checklist

• PR targets the main branch.
• Commits follow Conventional Commits
  (feat(...), fix(...), docs(...), …).
• npm run lint and npm run format:check pass.
• npm run typecheck passes.
• npm test passes and coverage stays at or above the 80% gate.
• New behavior is covered by unit tests (mock-based; no network or
  credentials required).
• No secrets, API keys, internal endpoints, or personal data are included.
• User-facing changes are reflected in README.md / DOCUMENTATION.md where
  relevant.

Notes for reviewers

The implementation is intentionally narrow and follows #223's existing pattern:
capture the swallowed error, honor the existing --debug flag, emit to stderr,
and preserve normal output and exit behavior.

The managed-target read failure occurs inside isVerifySkillInstalled(), so this
PR adds an optional best-effort diagnostic callback rather than changing the
function's return behavior. The callback is isolated with its own error guard so
diagnostic failures cannot affect command execution.

The branch changes only:

• src/index.ts
• src/lib/skill-nudge.ts
• src/lib/skill-nudge.test.ts

Full lint, format, typecheck, unit-test, and coverage verification is left to the
repository CI on this PR.

Summary by CodeRabbit

• New Features

  • Added optional debug output for skill-nudge processing, including skipped nudges and unreadable targets.
  • Added diagnostic reporting for errors encountered while checking skill installation status.

• Bug Fixes

  • Improved resilience when profile lookups, managed targets, warning output, or debug output fail.
  • Preserved warning messages even when diagnostic callbacks encounter errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b191a26d-21ea-46ae-bc54-a81cd4d5751a

📥 Commits

Reviewing files that changed from the base of the PR and between 40d18d2 and 6208369.

📒 Files selected for processing (3)

• src/index.ts
• src/lib/skill-nudge.test.ts
• src/lib/skill-nudge.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

Walkthrough

The skill-nudge pre-action now receives the global --debug flag. Debug mode reports swallowed profile lookup and managed-target read failures to stderr. Normal warnings, JSON output, and non-throwing behavior remain unchanged.

Changes

Skill-nudge diagnostics

Layer / File(s)	Summary
Presence diagnostic contract src/lib/skill-nudge.ts	Skill presence checks report unreadable managed targets through an optional callback. Callback failures remain swallowed.
Debug-enabled nudge flow src/lib/skill-nudge.ts, src/index.ts	The pre-action hook forwards the debug flag. Skill-nudge handling emits guarded diagnostics while preserving existing warning and command behavior.
Diagnostic regression coverage src/lib/skill-nudge.test.ts	Tests cover debug-only diagnostics, callback isolation, JSON-mode silence, warning preservation, and failing debug output sinks.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🟡 Moderate · up to 62083

The PR adds debug-only diagnostics without changing normal command behavior, but a duplicate declaration in the test file would prevent the test suite from loading. Merge should wait until that test syntax issue is corrected or explicitly accepted.

Sequence Diagram(s)

sequenceDiagram
  participant PreActionHook
  participant maybeEmitSkillNudge
  participant isVerifySkillInstalled
  participant stderr
  PreActionHook->>maybeEmitSkillNudge: pass debug flag
  maybeEmitSkillNudge->>isVerifySkillInstalled: check skill presence
  isVerifySkillInstalled-->>maybeEmitSkillNudge: return presence or report read error
  maybeEmitSkillNudge->>stderr: write debug diagnostic when enabled
  maybeEmitSkillNudge-->>PreActionHook: preserve non-throwing result

Loading

Suggested reviewers: ruili-testsprite

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: logging suppressed skill-nudge errors in debug mode.
Linked Issues check	✅ Passed	The changes satisfy issue #285 by threading debug context, adding diagnostics, preserving behavior, and testing failure isolation.
Out of Scope Changes check	✅ Passed	The changes remain focused on debug diagnostics and regression coverage for the scoped skill-nudge error paths.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 3 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}