docs agent failed: timed out cloning large monorepo for docs scan

TL;DR

Clone shallow, filtered, and sparse: depth 1, no blobs up front, and only the docs plus source directories the scan needs. A full monorepo clone downloads history the docs scan never reads. Shallow plus sparse turns a 20-minute clone into a sub-minute one.

docs agent failed: timed out cloning large monorepo for docs scan

Steps

1. Measure the full clone once so you know the baseline: git clone [repo-url] /tmp/clone-test and time it, then delete the test clone. Expected: you have a number to beat.
2. Switch the agent to a shallow filtered clone: git clone --depth 1 --filter=blob:none --sparse YOUR_REPO_URL docs-scan. Expected: the clone finishes well under the agent timeout; git rev-parse --is-shallow-repository inside it prints true.
3. Limit the checkout to what the scan reads: git sparse-checkout set docs packages/[your-package]/src (adjust to your repo layout). Blobs for other directories download on demand only. Expected: the working tree contains just docs and the needed sources.
4. Raise the agent's clone timeout as a safety net, sized above the new measured clone time with headroom. Expected: normal variance no longer trips the timeout.
5. Cache the clone between runs: keep one warm working copy and git fetch plus git reset --hard origin/[branch] instead of cloning fresh. Expected: repeat scans start in seconds.

Use this when

• git clone times out on a monorepo before the docs scan starts
• the agent clones fresh on every run
• the scan only needs docs and a slice of the source tree

Not for this skill when

• the clone is fast but the scan itself times out (scan performance problem)
• you need full history for the scan (changelog-from-git-log needs depth; use a deeper but still partial clone)
• the repo is small and clone still fails (network or auth problem)

Variant phrasings

• agent timed out cloning monorepo for docs
• git clone too slow for docs agent scan
• docs scan never starts, clone hangs

Why it happens

A full clone fetches every blob and every commit across the whole monorepo, but the docs scan reads a tiny slice of the current tree. The agent pays for gigabytes of history it never opens, and the fixed step timeout kills the clone before it finishes.

Edge cases

• Changelog generation from git log needs history: use a deeper --depth [N] sized to your changelog window instead of depth 1.
• Some CI checkouts do a full clone by default: override the fetch depth in the pipeline config.
• Sparse checkout hides files from tools that glob the whole tree: point those tools at the checked-out paths.
• Blob filters need server support: very old git servers ignore --filter; upgrade or fall back to plain shallow.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_vmoHJdryCn6Uh253GPgQRQ