Command Code loops/retries when writing large markdown handoff docs, only succeeds after splitting into smaller files

[josephalai]

Summary

Command Code repeatedly loops/retries when asked to analyze a codebase and write a large markdown handoff/spec document, especially when the requested output is one large file. The agent appears to repeatedly restart or resend the same “I’ll write it now / let me start writing” style messages instead of actually completing the file.

This happened in two separate projects, in two different folders, with two different prompts. In both cases, the task only completed after I instructed Command Code to stop trying to write one monolithic file and instead split the output into multiple smaller markdown files.

Trace ID from one occurrence:

5054acc945fbd22906a86e2688409796

This affects my workflow because I use Command Code to audit codebases and generate long handoff/spec documents. When the output is large, Command Code gets stuck in a retry/planning loop instead of producing the requested deliverable.

Expected Behavior

Command Code should:

1. Enter /plan mode and analyze the codebase according to the provided audit prompt.

2. Finish the plan/research phase.

3. Exit or allow switching out of /plan when instructed.

4. Write the requested markdown handoff/spec document to the specified path.

5. If the requested file is too large, either:

   • write it successfully in chunks to the same file, or
   • clearly state that the file is too large and ask/suggest splitting it into smaller files.

In this case, the expected deliverable was:

./docs/handoff/codebase-audit-phase2.md

The prompt explicitly instructed Command Code not to modify existing files, not to implement anything, and to create only that one markdown file.

Actual Behavior

Command Code analyzed the codebase but then appeared to get stuck before writing the large markdown file. It repeatedly produced “thought” cycles and messages indicating it was about to write the document, but it did not successfully complete the requested one-file output.

The behavior was roughly:

1. Command Code analyzed the project.
2. It appeared to remain stuck in /plan.
3. I manually instructed it to write the document.
4. It still repeated the same style of message/restart loop instead of writing the requested file.
5. The issue repeated multiple times.
6. Eventually the session hit a network/retry failure.
7. The task only completed after I explicitly told it to abandon the monolithic file and split the output into multiple smaller markdown files.

Important detail: this happened twice, in two different project folders, with different prompts, but both tasks involved creating long handoff/spec markdown documents.

There also appeared to be inconsistent behavior around /plan mode. In one run, Command Code wrote some files successfully into the project directory while apparently still in plan mode, then later claimed plan mode prevented writing outside ~/.commandcode/plans/. It then repeatedly reasoned about whether to exit plan mode, retry writes, or create a plan file, instead of cleanly proceeding.

The successful workaround was to tell it:

Instead of writing one monolithic file, please create multiple documents, one for each section.

After that, Command Code was able to create smaller markdown files and complete the task.

Steps to reproduce the issue

1. Open a project with a sufficiently large codebase.

2. Create or provide an audit prompt that requires Command Code to inspect the codebase and generate a long markdown handoff/spec document.

3. Start Command Code in /plan mode with a prompt like:

   /plan Read the file at ./docs/handoff/codebase-audit-prompt.md in full before doing anything else. That file contains your complete instructions, full context about what this application is, what has already been built, what new features are being designed, and exactly what you are auditing and why.
   
   Follow every instruction in that file precisely. Use your own judgment to locate relevant files throughout the codebase — do not limit yourself to only the paths explicitly named. If a file that answers one of the audit questions is located somewhere other than expected, find it and include it.
   
   Your only deliverable is one new markdown file written to ./docs/handoff/codebase-audit-phase2.md.
   
   Do not modify any existing files. Do not implement anything. Do not create any file other than ./docs/handoff/codebase-audit-phase2.md.
   
   

Let Command Code analyze the project.
Once analysis is complete, instruct it to write the document.
Observe that it repeatedly enters long “thought” cycles and appears to restart/retry rather than writing the requested long markdown file.
Try manually instructing it to leave /plan mode and write the document.
Observe that it still loops/retries and does not successfully complete the one large markdown output.

Then instruct it to split the document into multiple smaller files, for example:

It appears that long files do not work for you. Abandon the one monolithic mega long file. Make a new directory and output into ./docs/handoff/advisor-and-routines/{1,2,3,4,...,n}-{section-name}.md
Observe that Command Code is then able to complete the task by writing smaller files.

Command Code Version

### Command Code Version

0.40.0

### Operating System

macOS

### Terminal/IDE

iTerm2

### Shell

zsh

### Additional context

This happened in two separate projects, in two different folders, with two different prompts. Both tasks involved analyzing the codebase and writing a long markdown handoff/spec document.

The issue seems connected to one or both of the following:

1. Large single-file markdown output, likely over 1,000 lines.
2. `/plan` mode not cleanly transitioning into execution/writing mode.

In one occurrence, Command Code appeared to repeatedly think through the same decision:

- whether it was still in `/plan`
- whether plan mode prevented writing to the project directory
- whether it should retry writing
- whether it should exit plan mode
- whether it needed to create a plan file first

Instead of cleanly exiting plan mode or writing the requested file, it looped through variations of this reasoning.

One session eventually produced:

```text
⚠ Error: Network connection lost.

Type "continue" to try again. If the issue persists, contact
support: https://commandcode.ai/discord

Trace ID: 5054acc945fbd22906a86e2688409796

The workaround was to explicitly instruct Command Code to stop trying to create one monolithic markdown file and instead create a directory of smaller files, one per section. Once I gave that instruction, the task completed successfully.

Example successful workaround instruction:

It appears to be that long files do not work for you. Abandon the one "monolithic" mega long file. Thus, make a new directory & output into ./docs/handoff/advisor-and-routines/{1, 2, 3, 4, ..., n}-{section-name}.md

After this, Command Code created smaller files successfully, for example:

WRITE [docs/handoff/advisor-and-routines/2-desire-data-model-and-api.md]
Created docs/handoff/advisor-and-routines/2-desire-data-model-and-api.md

The core problem is that Command Code does not seem to gracefully handle very large requested markdown outputs as a single file, and it does not clearly recover by suggesting file splitting or automatically chunking the write.