Skip to content

feat(framework): collect business knowledge in the repo (#537)#559

Merged
suleimansh merged 1 commit into
mainfrom
feat/537-business-knowledge
Jul 15, 2026
Merged

feat(framework): collect business knowledge in the repo (#537)#559
suleimansh merged 1 commit into
mainfrom
feat/537-business-knowledge

Conversation

@suleimansh

Copy link
Copy Markdown
Member

Closes #537

Both bullets from the issue's Implementation section.

1. The docs go on the Context: line. .the-framework/README.md, DECISIONS.md and KNOWLEDGE-BASE.md join the #439 context line on every run, alongside the directories the user selects. One KNOWLEDGE_DOCS const; a test pins the post-merge prompt against it so the two halves cannot name different files.

2. The post-merge prompt asks the agent to update them. New ## Business knowledge section:

## Business knowledge

Consider whether the changes introduced by <SESSION_NAME> taught you something that belongs in these documents, and update them if so (create one if it doesn't exist yet):
- `.the-framework/README.md` (whole repo overview)
- `.the-framework/DECISIONS.md` (decisions taken, and why)
- `.the-framework/KNOWLEDGE-BASE.md` (business knowledge about the project)

Only write what a future agent would need and cannot get from the code itself.

BRAINSTORMING.md is left out, per the issue.

Two calls made here

Ran it for real

Real binary, real git repo, ~$1. A repo whose DECISIONS.md said "flat pricing, no surge" while the session's commit shipped surge pricing:

  • The agent read DECISIONS.md off the context line unprompted, and caught the contradiction.
  • It wrote a KNOWLEDGE-BASE.md that records what the code cannot: that the 1.4 multiplier has no recorded derivation, that bookedHour has no timezone attached, and that sameDay is caller-supplied so a client could opt out of surge. It explicitly left the surge rationale out, because that one is in a code comment.
  • Both maintenance gates came back negative on a 7-line change, so no TODO file. The conditions work.

composeRunSystem 4475 -> 4573 chars.

Green: framework tests pass except runCli --daemon backgrounds the dashboard, which fails identically on clean main here (a daemon is already live on :4200) — pre-existing and environmental, not from this change.

Two halves, per the issue's Implementation section.

Context: every run now carries .the-framework/README.md, DECISIONS.md and
KNOWLEDGE-BASE.md on the #439 `Context:` line, so the agent reads what the
project already knows about itself. They ride with the built-in system prompt,
not with the user's own dirs: --vanilla means no framework-authored prompt.

Post-merge: a `## Business knowledge` section asks the agent to fold back what
the session taught that the code cannot show.

--eco-auto-maintenance dropped the whole post-merge run, which was right when
that prompt was exactly the maintenance section. It no longer is, so the flag
now drops just `## Maintenance` and business knowledge survives it.
@suleimansh

Copy link
Copy Markdown
Member Author

Known limitation, tracked separately in #560: the post-merge run branches before writing, so the knowledge docs land on a branch nobody merges. Older than this PR (the #556 TODO entries do the same) and not widened into it.

@suleimansh
suleimansh merged commit b22337a into main Jul 15, 2026
2 checks passed
@suleimansh
suleimansh deleted the feat/537-business-knowledge branch July 15, 2026 23:54
@brillout

Copy link
Copy Markdown
Member
  • Let's remove README.md for now (very likely to be redundant with already existing README.md)
  • Let's move the files to the repo root
  • Add the comments also in the context
    - `DECISIONS.md` (decisions taken, and why)
    - `KNOWLEDGE-BASE.md` (knowledge and insights related to the project)
  • post-merge is a misnommer, it should be called to something else e.g. on-before-mergeable
  • I don't like the prompt, change it to:
    ## Business knowledge
    
    If you didn't already, consider updating the following based on the changes and discussions of ${{ tf.session_name }} (you can create the files if they're missing):
    - `DECISIONS.md` (decisions taken, and why)
    - `KNOWLEDGE-BASE.md` (knowledge and insights related to the project)
    
    Only write what a future agent would need and cannot get from the code itself.

@suleimansh I don't mind AI slope e.g. (DRY issues) for the code, but for all the prompting let's always take an extra look and give it extra thoughts. Thoughful prompts, always. Zero vibe-coded half-hassed prompts, ever. Feel free to ping me for everything related to prompting. When AI will apply the changes above, let's review carefuly whether its changes related to prompting matches what I said above (zero tolerence for AI slope in prompting).

suleimansh added a commit that referenced this pull request Jul 16, 2026
…xt (#591) (#593)

Apply Rom's #559 review of the #537 business-knowledge feature:
- drop README.md from the knowledge docs (the repo's own README covers the overview)
- move DECISIONS.md / KNOWLEDGE-BASE.md to the repo root, not .the-framework/
- carry each doc's one-line gloss into the injected Context: too, as bullets
- replace the ## Business knowledge prompt with Rom's verbatim wording

Closes #591
suleimansh added a commit that referenced this pull request Jul 16, 2026
…) (#600)

It fires on setReadyForMerge(), before the merge, so "post-merge" was a
misnomer (Rom, #559). Renamed the concept end to end: the --post-merge flag
is now --on-before-mergeable; runPostMerge / renderPostMergePrompt /
PostMergeContext / POST_MERGE_PROMPT become their OnBeforeMergeable
equivalents; the prompt file is on_before_mergeable_prompt.md; the drift
snapshot and the dashboard preference key (postMergeQuality ->
onBeforeMergeableQuality) follow.

No agent-facing prompt text changed: the string "post-merge" never appeared
in any prompt, only in code, comments, filenames and the flag. The dashboard's
visible "Post-merge cleanup" label is left as-is pending a copy decision.

Framework 541/1 skip/0 fail, drift green, framework + dashboard typecheck clean.

Closes #592
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Product management: collect business knowledge

2 participants