docs(defuddle): document shell-level timeout pattern for slow URLs

[jeremysoccer45]

Draft PR — Defuddle: configurable timeout for web fetches

Branch

improve/defuddle-timeout-handling (local only; commit SHA 7e91650)

Suggested PR title

docs(defuddle): document shell-level timeout pattern for slow URLs

Note: original draft title was feat(defuddle): add configurable timeout for web fetches, but since the change is documentation-only (the skill has no helper code to patch), docs(...) is more accurate. Use whichever you prefer.

Summary

The defuddle skill currently tells Claude to invoke defuddle parse <url> --md with no timeout. Because the upstream defuddle CLI has no built-in --timeout flag, a slow or hung server can stall the skill indefinitely with no user feedback. This PR appends a "Handling slow or unresponsive URLs" section to SKILL.md that documents shell-level timeout patterns (timeout 30 ... on Linux/macOS/git-bash, Start-Job + Wait-Job -Timeout 30 on PowerShell), establishes 30 seconds as the default, and tells Claude what to do when the timeout fires (fall back to WebFetch or report; do not silently retry).

Motivation

QB-IMPROVE round 1 gap-analyst flagged "defuddle timeout handling" as needing improvement. The failure mode is concrete: a user pastes a URL whose origin is slow or non-responsive, the skill calls defuddle parse <url> --md, the underlying fetch hangs, and Claude waits with no recovery path. There is no upstream CLI flag for this — verified against the defuddle CLI README — so the only available fix is to instruct the agent to wrap the call in a host-level timeout.

Implementation

• Touched: skills/defuddle/SKILL.md (body only — no helper code exists in this skill).
• Appended a single new section, "Handling slow or unresponsive URLs", after the Output formats table.
• Default timeout: 30 seconds. Chosen because typical web-page fetches resolve in under 5s; 30s gives a wide margin for legitimately slow but live servers without making the user wait absurdly long for a dead one.
• Documented two shells: timeout 30 defuddle parse <url> --md (POSIX / git-bash) and Start-Job + Wait-Job -Timeout 30 (PowerShell).
• Documented override: timeout 60 ... for known-slow sources (long PDFs, large pages).
• Documented failure handling: on timeout, fall back to WebFetch or report to the user; do not silently retry.
• Not changed: the SKILL.md frontmatter (name, description, license, version, tags). No version bump because behavior of well-behaved URLs is unchanged; this is purely additive guidance.

Test plan

Manual repro (before/after):

• Before (on main): invoke the defuddle skill on a deliberately slow URL such as http://httpstat.us/200?sleep=120000. Observe that the call hangs for 2 full minutes with no Claude-side timeout.
• After (on improve/defuddle-timeout-handling): re-run the skill with the same URL. Claude should now wrap the call as timeout 30 defuddle parse ..., the call should error after 30s with exit code 124, and Claude should report the timeout / offer WebFetch fallback rather than waiting silently.
• Override path: invoke against the same slow URL but explicitly request a 60s timeout in the prompt. Claude should wrap as timeout 60 ... and behave accordingly.
• Regression: invoke against a normal fast URL (e.g., https://example.com). Output should be identical to pre-PR behavior — the wrapper adds zero latency for sub-30s responses.
• Validator: python tools/validate_skill.py skills/defuddle/SKILL.md exits 0 (verified locally before commit).

Backward compatibility

• Existing invocations against fast URLs are unchanged — the wrapper only fires on slow ones.
• Frontmatter is byte-identical to main, so any tooling that reads name/description/version is unaffected.
• No new dependencies. timeout is in coreutils on Linux/macOS and ships with git-bash on Windows; Start-Job/Wait-Job are built into PowerShell 5.1+.
• No breaking changes.

Diff summary

 skills/defuddle/SKILL.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(Output of git diff main..improve/defuddle-timeout-handling --stat.)

Reviewer notes

• Why docs-only and not a helper script? The defuddle skill is a thin instructions-only SKILL.md — there is no Python/Node helper to patch. Adding a wrapper script just to enforce a timeout would be more invasive than the gap warrants and would require users to install something beyond npm install -g defuddle. Documenting the shell pattern matches how the rest of the skill is written.
• Why 30s default? A round 1 sibling skill (obsidian-summarize-url) uses timeout 30 for its Firecrawl-based fetch path; matching that convention keeps timeout behavior consistent across content-extraction skills.
• Why no --timeout <seconds> flag on defuddle itself? Verified against the upstream CLI README — defuddle parse has no fetch-timeout flag (only --output, --md/--markdown, --json, --property, --debug, --lang). A shell-level timeout is the only available lever.
• Future work (not in this PR): if defuddle ever gains a native --timeout, this section should be replaced with the native flag. Filed mentally; no issue created.
• Push status: branch is local only. Run git push -u origin improve/defuddle-timeout-handling and gh pr create when ready.