README: the standard loop re-runs simplify and review after ce-work, and says ce-brainstorm reads learnings, which it does not

Open Beginner friendly
#2,091 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
documentation

Research direction

Read the standard loop in README.md alongside docs/guides/README.md and skills/ce-help/references/workflow.md, then check the cited ce-work and ce-brainstorm references before editing. Align the README’s loop and learning claims with the documented skill behavior, choosing whether brainstorm should read learnings or the wording should say that ce-plan does. Done when the inconsistent descriptions are corrected.

Written by the indexing model from the issue text.

Description

Two sentences in the README's loop section describe the loop differently from the skills.
They sit a few lines apart, so I'm filing them together.

1. The standard loop repeats steps that /ce-work already ran.

The README says the core loop is six steps (README.md:128), and the standard loop has the user type /ce-work, then /ce-simplify-code, then /ce-code-review, then /ce-compound (README.md:155-164).

ce-work already runs both of the middle steps.
Its shipping workflow invokes ce-simplify-code at 30 or more changed lines (ce-work/references/shipping-workflow.md:11-13) and requires a completed ce-code-review receipt before shipping (ce-work/references/shipping-workflow.md:19-23).
ce-help's routing doc says so directly (ce-help/references/workflow.md:47):

Do not send someone to repeat a step a skill runs itself. ce-work carries work through simplification, review, and the PR, and that PR gets watched.

The guides catalog shows a third version: four steps, with simplify and review as on-demand tools (docs/guides/README.md:13-31).

A new user who follows the README runs a second simplify pass and a second multi-agent review on a diff that already has a review receipt, after ce-work has opened the PR.

2. /ce-brainstorm does not read learnings.

The README (README.md:139) and the guides catalog (docs/guides/README.md:31) both say the next /ce-brainstorm and /ce-plan read the learnings /ce-compound writes as grounding.
ce-plan does: it builds a search-root list of <root>/solutions/ plus any packs and dispatches the learnings researcher over it (ce-plan/references/research.md:21-29).
ce-brainstorm doesn't.
Its grounding scout looks for "the most relevant existing artifacts (brainstorms, plans, specs, feature docs)" (ce-brainstorm/references/dialogue.md:41), and <root>/solutions/ appears in the skill only as a place decisions can go instead of a brainstorm doc (ce-brainstorm/references/plan-write.md:5).

The README calls this return arrow "the whole point", so a reader plans around brainstorms that remember, and they don't.

Possible fixes (your call which matches the intent):

  1. Drop /ce-simplify-code and /ce-code-review from the standard loop and the six-step sentence, matching the guides catalog and ce-help.
  2. For brainstorm, either add <root>/solutions/ to the grounding scout's list, or change both sentences to say that /ce-plan reads the learnings.

#1976 added the "What already runs on its own" section to ce-help and edited the README in the same pull request, but left the standard loop as it was.

Found by reading the files at 8f76146, not by a live run.

Dominant language
TypeScript
Stars
25.6k
Forks
2.1k
Avg merge
3h 55m
Merged PRs (30d)
170

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EveryInc/compound-engineering-plugin

All issues in EveryInc/compound-engineering-plugin

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.