Accretion alone captures only the peripheral terms that surface through
friction; the stable-central nouns a project is built around never break,
so they never appear in a learning and never get defined. The live output
(PR #896) proved it: a scoped run produced Beta skill / Confidence anchor /
Autofix class with zero core domain nouns, so the captured terms dangled
against undefined siblings.
Reverse the no-cold-start-scan stance and seed proactively:
- concepts-vocabulary.md: add accretion-vs-seeding framing and a Seed goal
expressed as goal + qualifying bar (codebase sets the count, no fixed
number); distinguish in-scope seeding from repo-wide bootstrap; require
entries to lean only on defined siblings or general English; sharpen the
no-current-config rule (state behavior, not threshold numbers).
- ce-compound: stop refusing CONCEPTS.md bootstrap — redirect standalone
requests to ce-compound-refresh; seed the learning's area at creation;
widen the opportunistic-fix pass into a bounded coherence-neighborhood
refresh.
- ce-compound-refresh: standalone bootstrap now asks "create the concept
map" vs "run a refresh cycle" (create does the repo-wide seed); creation
seeds in-scope core nouns; every run reconciles in-scope core nouns as a
safety net for stable-central terms.
Both concepts-vocabulary.md copies kept byte-identical.
Adds an eval suite that tests whether ce-sessions findings preserve
terminology resolution context — specifically, whether distinctive
coined terms and their resolution rationale survive the
session-historian synthesis step intact.
Four test cases with ground truth from recently merged PRs:
- synthesis-gate-recovery (PR #822) — distinctive term recovery
- mode-headless-semantic-alignment (PR #813) — multi-piece nuance
- tangential-term-recovery — indexing-gap test
- near-miss-false-positive — discriminating-power test
Two-stage grader: programmatic substring match per criticality tier,
plus LLM-graded context preservation. Variance protocol: 3 runs per
eval.
This suite was built during PR #838's design exploration to validate
a load-bearing assumption (that ce-sessions findings could feed
ce-compound Phase 2.4's vocabulary scan). That assumption was
ultimately retired in favor of doc-and-conversation-only scanning,
so the suite is not load-bearing for PR #838. Kept as future
infrastructure for validating ce-sessions's behavior as the skill
evolves — e.g., when changing the session-historian synthesis prompt
or adjusting scan-window defaults.
Iteration-1 results (executed via skill-creator framework, captured
to /tmp/compound-engineering/ce-sessions/evals/iteration-1/) showed
ce-sessions preserved terminology strongly across all 4 evals with
100% must-tier recall and 0% stddev — but this is a capability test
of the skill in isolation, not a test of any specific integration.
Earlier in this branch, Phase 2.4's vocabulary scan was extended to
include ce-sessions findings as a third input. Architectural review
surfaced two problems with that wiring:
- ce-compound's payload to ce-sessions includes a "directly relevant
to this specific problem; ignore unrelated work" filter rule, which
actively suppresses the tangential context where vocabulary often
lives. The filter is correct for fix-context retrieval but wrong
for vocabulary capture — the two needs pull in opposite directions.
- Wiring named external sources into Phase 2.4 creates maintenance
debt: every new research input (future Slack research, Linear
context, etc.) requires updating the scan input list.
Revert to scanning only the new doc and the surrounding conversation.
Both are always available to the orchestrating agent — no plumbing,
no filter-rule mismatch. Conversation catches mid-dialogue vocabulary
resolutions that didn't make the doc; the doc captures terms the
writer judged worth recording. Terms that emerged only in
non-conversation sources (research subagents, ce-sessions) flow into
Phase 2.4 indirectly via the doc-writer's synthesis, which is the
right level of curation.
If external-source vocabulary mining ever becomes a real need, design
it as a dedicated dispatch with a vocabulary-tuned payload, not as a
Phase 2.4 scan input.
After comparing against grill-with-docs (third-party skill for a
similar artifact), sharpen how CONCEPTS.md is framed across the
plugin and close a terminology-capture gap.
In references/concepts-vocabulary.md (both copies):
- Lead with "Be opinionated" as the file's stance.
- Replace the enumerated "What never appears" list with the principle
"The file stands on its own" — one mental test that subsumes the
existing exclusions and extends to cases we hadn't enumerated.
- Add aliases-per-entry format (*Avoid: X, Y*) so retired synonyms
ride alongside their canonical term.
- Tighten "Per entry" to one-sentence base definition; explicit
second-paragraph allowance for non-obvious behavioral rules only.
- Add optional Relationships section when structure is load-bearing.
- Rename "Resolved ambiguities" to "Flagged ambiguities."
In ce-brainstorm Phase 1.1: reframe CONCEPTS.md as the project's
authoritative vocabulary (was: shared domain vocabulary that anchors
terms here). Carries authority across the whole session without
needing to restate "use canonical names" at every downstream phase.
In ce-compound Phase 2.4: extend the vocabulary scan to include
ce-sessions findings when Full mode runs. Session findings carry
terminology resolution context from prior brainstorm, plan, and
work dialogues; without this, that context was being pulled in for
research but ignored at capture time.
Also replace "scratchpad" with "catch-all" across four locations —
clearer naming of the failure mode (dumping ground for things that
don't fit elsewhere).
The "at least one qualifying term" gate in ce-compound Phase 2.4 and
ce-compound-refresh Phase 4.5 step 3 could allow a permissive agent
to seed CONCEPTS.md from a routine bug fix that only surfaced class
or table names dressed up as entities. The criteria in
concepts-vocabulary.md are correct but judgmental, and lenience at
the creation moment seeds a thin file the team didn't actually need.
Add an explicit "hold the qualifying bar conservatively at creation"
rule to both skills. Borderline terms defer to a later run with
stronger signal. The conservatism is quality, not count — the
asymmetric-trap defense against minimum-count gating is preserved.
Updates to an existing file continue to follow normal criteria.
When ce-compound or ce-compound-refresh first creates CONCEPTS.md,
write a short preamble at the top explaining what the file is, how
it accretes, and what it isn't (glossary only, not a spec or
scratchpad). Visible prose under the # Concepts heading so both
humans browsing the rendered file and agents reading the raw file
see the same framing — an HTML comment would have hidden the model
from human readers on GitHub for no real gain.
ce-compound Phase 2.4 and ce-compound-refresh Phase 4.5 establish the
glossary-only rule for CONCEPTS.md but only apply it prospectively to
new entries. Existing drift (file paths, class names, function
signatures, status/owner metadata) survived every run.
Add active correction at two scopes matched to each skill's character.
ce-compound fixes opportunistically — only entries being touched or
adjacent to them — because compound is not an audit. ce-compound-refresh
runs a full sweep as Phase 4.5 step 6 because refresh is an audit.
Extend the refresh report's CONCEPTS.md line to surface the scrubbed
count alongside added and refined.
Users may type "create my CONCEPTS.md" without an existing learning
corpus, particularly in cold repos. Previously this had no clean
routing path — ce-compound's description didn't match the request,
so the main agent ad-hoc'd a response.
Update ce-compound's description to declare CONCEPTS.md as a stated
responsibility, and add a short intercept block near the top of the
skill body. The block redirects without performing a bootstrap:
explains the accretion model, notes that cold-start codebase scans
are intentionally unsupported (the qualifying bar is judgmental),
and offers three real next steps — run ce-compound on a real
learning, ce-compound-refresh on an existing corpus, or hand-edit
directly.
ce-brainstorm Phase 1.4 and ce-plan §5 gap-fill are contributors to
CONCEPTS.md but neither loads concepts-vocabulary.md, so the criteria
preventing implementation details from creeping in lived only where
the contributors couldn't see them. Add an inline negative-framing
line to both ("domain entities, named processes, and status concepts
with project-specific meaning only — not file paths, class names, or
implementation decisions"). Also drop rationale tails that did not
change agent behavior at runtime.
External test surfaced two structural failures in ce-compound that an
LLM orchestrator can hit even when following the skill text:
1. ce-sessions return read as a terminus. Phase 1's parallel block ended
on three subagents, then ce-sessions ran synchronously as the final
input. Phase 2 said "WAIT for all Phase 1 subagents" -- which an LLM
could read as not including the skill call. The agent emitted
ce-sessions's output to the user and stopped.
Fix: add a forward-edge sentence at the end of step 4 ("ce-sessions
is the final Phase 1 input, not a workflow stop"), and broaden the
Phase 2 WAIT line to "all Phase 1 inputs" with an explicit note that
ce-sessions counts despite being a skill rather than a subagent.
2. Phase 2.4's "skip entirely if no terms qualify" let agents vibe-judge
"nothing qualifies" from the inline criteria teaser and skip reading
references/concepts-vocabulary.md entirely -- the opposite of the
stated intent.
Fix: invert the phase so "First, read the reference" is the
unconditional opener, drop the inline criteria teaser (per the
no-duplication-with-references principle), and replace the silent-
skip path with a visible "Vocabulary capture: scanned, no qualifying
terms" outcome the agent must record.
Propagated the Phase 2.4 fix to ce-compound-refresh's Phase 4.5 -- same
structural risk, same shared reference, both phases introduced on this
branch. Tightened both success-output templates from the ambiguous
"skipped (no qualifying terms)" to the unambiguous "scanned, no
qualifying terms" so the audit signal cannot be confused with "didn't
bother to check".
Step 6's amend/follow-up commit logic only mentioned step 4 (docs/solutions
discoverability edit). When step 4 produces no edit but step 5 (the new
CONCEPTS.md discoverability path) does, the new instruction-file change
would be left out of the commit sequence and end up as a dirty worktree
or an omitted edit. Cover both edit paths in step 6.
Adds a domain-vocabulary artifact maintained as a side effect of compounding.
CONCEPTS.md is the substrate that learnings cite — entities, named processes,
and status concepts with project-specific precise meaning. Lazy creation,
opportunistic AGENTS.md discoverability, no user prompts.
Ownership model:
- ce-compound and ce-compound-refresh create and maintain the file. Both also
surface CONCEPTS.md to AGENTS.md/CLAUDE.md on first creation via the existing
Discoverability Check, so future agents discover the file.
- ce-brainstorm and ce-plan are contributors only — they add to or refine
CONCEPTS.md when terms surface, but skip writes entirely when the file
doesn't exist. Avoids speculative bootstrapping from pre-implementation work.
- ce-learnings-researcher reads CONCEPTS.md as grounding before keyword
extraction so result distillation uses canonical terminology.
ce-compound and ce-compound-refresh both bundle a concepts-vocabulary.md
reference with inclusion criteria, format rules, and an illustrative example.
ce-brainstorm and ce-plan intentionally do not — they learn format from the
existing file's contents. Plugin AGENTS.md gains a note that the two reference
copies must stay in sync.
Trevin Chow
github-actions[bot]
Kieran Klaassen
Brian Paden