mirror of
https://github.com/azaion/ui.git
synced 2026-06-21 08:41:10 +00:00
Oleksandr Bezdieniezhnykh
8e90e24f5a
Bring this repo's .cursor/ in line with the suite monorepo root .cursor/ so rules, skills, and autodev artifacts stay consistent across submodules and sibling repos. Co-authored-by: Cursor <cursoragent@cursor.com>
42 lines
2.3 KiB
Plaintext
42 lines
2.3 KiB
Plaintext
---
|
|
description: "Use chunked writes (Write + StrReplace marker pattern) for large generated files, especially after a monolithic Write fails"
|
|
alwaysApply: true
|
|
---
|
|
# Large File Writes — Chunk on Failure
|
|
|
|
When a `Write` call to a single file fails (timeout, payload limit, "Invalid arguments", or any tool error) and the intended content is large (>~500 lines or >~50 KB), do NOT retry the same monolithic Write. Switch to chunked writes:
|
|
|
|
1. **First Write** — create the file with header + table of contents (if applicable) + an explicit append marker, e.g.
|
|
|
|
```
|
|
<!-- INSERTION_POINT do-not-remove-until-final-chunk -->
|
|
```
|
|
|
|
2. **Each subsequent chunk** — use `StrReplace` to replace the marker with `<new content>\n<marker>` so the marker stays at the end. This is idempotent: if a chunk fails, retry it without losing earlier chunks.
|
|
|
|
3. **Final chunk** — `StrReplace` removes the marker.
|
|
|
|
## Why
|
|
|
|
- Tool argument size limits and transient failures hit large monolithic writes hardest. Retrying the same large payload typically fails for the same reason.
|
|
- Chunked writes are recoverable per chunk. The earlier chunks are durable on disk.
|
|
- A unique marker is greppable, visible in diffs, and stops accidental insertion in the wrong place.
|
|
|
|
## Triggers
|
|
|
|
- Generated documentation that aggregates per-component content (epics, design docs, multi-section architecture summaries, traceability dumps).
|
|
- Large fixture or test-data files written from a template.
|
|
- Any single-file artifact you can pre-estimate at >~500 lines.
|
|
|
|
## Do NOT chunk
|
|
|
|
- Files under ~200 lines — a single `Write` is faster, clearer, and easier to review.
|
|
- Source code files where appending breaks module structure (functions, classes, imports). Split into multiple files instead.
|
|
- Files where ordering of sections is computed late and inserting in the middle is required — use a single `Write` once the full content is known.
|
|
|
|
## Anti-patterns
|
|
|
|
- Retrying the same failed monolithic `Write` more than once. Twice is the limit; on the second failure, switch strategies.
|
|
- Using `Shell` with heredoc (`cat <<EOF`) or `echo >>` to append — these bypass the editor diff view and break the StrReplace contract for the next chunk.
|
|
- Embedding the marker so deep inside structured content that a chunk's `StrReplace` becomes ambiguous. Place the marker on its own line at the very end of the file.
|