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

```text
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