Skip to content

Open source CapCut alternative.

TypeScript

docs: a known gap is work left undone

David Lecf9e28e945e0
diff --git a/AGENTS.md b/AGENTS.md
index 7162c1df..1097f5b9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,7 +38,8 @@ Every Cut change has to hold on all four surfaces, and the plan for it says how:
- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.
- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.
- Keep replies short and action-oriented. For implementation questions, give the recommendation first, then one to three short bullets on why; when the answer is obvious, just say what to do. Skip long explanations, caveats, and "one last thing" sections; flag a real blocker or risk with "One issue:" and explain it briefly.
-- Never end a reply with a caveat, limit, bound, or "worth knowing" addendum. A problem gets fixed in the same turn it is found; anything that changes what the user does belongs in the body of the summary, said once.
+- Never dress a fact up as an aside. No "worth knowing", "worth flagging", "worth calling out", "one thing to note", "for future reference", "the part that matters here" — and no other phrase that announces information as bonus insight. This holds anywhere in a reply, not just at the end. If it matters, state it plainly as part of the work; if it does not, cut it. A problem gets fixed in the same turn it is found, and anything that changes what the user does belongs in the body of the summary, said once.
+- Never ship a known gap. Finding a case that does not work — another type, another surface, another shelf — means fixing it in the same turn, before the summary. A line explaining what still fails is the work left undone; do the work. Ask only when closing it is a scope fork or a destructive action.
- Make the decision and do it. Implement the obvious next step; never end with "if you want, I can…" or ask the user to say the word. Save questions for genuine scope forks and destructive actions.
- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.
- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7162c1df..1097f5b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,7 +38,8 @@ Every Cut change has to hold on all four surfaces, and the plan for it says how:
- When writing or editing any engineering doc under `docs/`, follow `docs/guides/eng-doc-style.md`.
- Write straight up — in prompts, docs, commits, code comments, summaries, and UI copy. State what a thing is, once, and stop. Never frame it against what it is not: no "X, not Y", no "X rather than Y", no "instead of Z", no "…, which is exactly what not to do". Cut filler.
- Keep replies short and action-oriented. For implementation questions, give the recommendation first, then one to three short bullets on why; when the answer is obvious, just say what to do. Skip long explanations, caveats, and "one last thing" sections; flag a real blocker or risk with "One issue:" and explain it briefly.
-- Never end a reply with a caveat, limit, bound, or "worth knowing" addendum. A problem gets fixed in the same turn it is found; anything that changes what the user does belongs in the body of the summary, said once.
+- Never dress a fact up as an aside. No "worth knowing", "worth flagging", "worth calling out", "one thing to note", "for future reference", "the part that matters here" — and no other phrase that announces information as bonus insight. This holds anywhere in a reply, not just at the end. If it matters, state it plainly as part of the work; if it does not, cut it. A problem gets fixed in the same turn it is found, and anything that changes what the user does belongs in the body of the summary, said once.
+- Never ship a known gap. Finding a case that does not work — another type, another surface, another shelf — means fixing it in the same turn, before the summary. A line explaining what still fails is the work left undone; do the work. Ask only when closing it is a scope fork or a destructive action.
- Make the decision and do it. Implement the obvious next step; never end with "if you want, I can…" or ask the user to say the word. Save questions for genuine scope forks and destructive actions.
- Update guides in `docs/guides/` only for major features or durable supported-behavior changes. Do not update guide docs for small styling tweaks, layout adjustments, copy changes, or implementation-only refactors.
- Keep guides explanatory. They should teach what the system is, how it works, and which boundaries matter; do not turn guides into feature inventories, implementation logs, duplicated code, or long file lists.