"Complete the project" feature should be updating documentation #232

Closed
opened 2026-10-21 10:49:27 -04:00 by cmoriarty · 2 comments
Owner

I'm doing the first real experiment with the combination of "Auto-plan" and "Complete the project". The first problem I noticed is that the agent is on the 3rd issue and the repo has no documentation whatsoever.

One big mission of Braid is transparency. Its why we have the live coding agent that can be interrupted and resumed. So for the case of auto-plan and complete the project, the user should have a way to go behind the agent and test out the software that exists. Without documentation, I'd have to ask the agent how to use it, or infer it myself from the code.

I think there should be an extra step added to the graph to update README at a minimum, and any other documentation the project my have. This could happen just before or just after the plan.next step. There should be some guidance given for the readme, to keep it short and sweet, but still informative enough to be able to test it, and get a good idea what it is and perhaps even how it looks (if relevant). If it already exists, then it should be updated to be correct.

I'm doing the first real experiment with the combination of "Auto-plan" and "Complete the project". The first problem I noticed is that the agent is on the 3rd issue and the repo has no documentation whatsoever. One big mission of Braid is transparency. Its why we have the live coding agent that can be interrupted and resumed. So for the case of auto-plan and complete the project, the user should have a way to go behind the agent and test out the software that exists. Without documentation, I'd have to ask the agent how to use it, or infer it myself from the code. I think there should be an extra step added to the graph to update README at a minimum, and any other documentation the project my have. This could happen just before or just after the plan.next step. There should be some guidance given for the readme, to keep it short and sweet, but still informative enough to be able to test it, and get a good idea what it is and perhaps even how it looks (if relevant). If it already exists, then it should be updated to be correct.
Author
Owner

I realize now that that there was a README with install instructions, so it is working well. It may still be worth having a new step specifically to ensure that docs are kept up to date.

I realize now that that there was a README with install instructions, so it is working well. It may still be worth having a new step specifically to ensure that docs are kept up to date.
Author
Owner

What shipped

  • The implementing briefs ask the README to say how to use the project (how to start it, its controls or main actions), not only how to run and test it.
  • The judge adds a criterion that the README tells a person how to use what it saw, and a README that leaves that out fails it.

No new step: the README is now part of what the fix loop checks.

Shipped in 5598ddf (OpenSpec change checks-that-match-the-brief, archived).

**What shipped** - The implementing briefs ask the README to say how to use the project (how to start it, its controls or main actions), not only how to run and test it. - The judge adds a criterion that the README tells a person how to use what it saw, and a README that leaves that out fails it. No new step: the README is now part of what the fix loop checks. _Shipped in 5598ddf (OpenSpec change `checks-that-match-the-brief`, archived)._
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#232
No description provided.