mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-21 08:41:12 +00:00
Oleksandr Bezdieniezhnykh
64542d32fc
Transitioned the autodev state to phase 21, reflecting the completion of Step 5 and the drafting of Step 6 epics. Revised the architecture documentation to clarify the roles of the Tile Manager and its components, ensuring accurate representation of the system's operational flow. Updated glossary entries for Flight State and Operator to incorporate recent changes and enhance clarity on component interactions and responsibilities.
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.
|