docs(solutions): refresh skill-design learnings#896
Merged
Conversation
…S.md Refresh the skill-design/ solutions cluster against the current codebase (12 updated, 2 kept as-is). - Modernize stale ce: colon skill naming to ce- hyphen throughout (now test-enforced), and the doc-review agent-path reorg (agents/document-review/*.agent.md -> flat agents/ce-*-reviewer.md). - ce-doc-review-calibration-patterns: trim superseded float-band content, point scoring to confidence-anchored-scoring, keep structural patterns. - beta-promotion-orchestration-contract: fix curly-quote frontmatter and correct a false slfg/contract-test claim (only lfg/autofix is enforced). - ce-prefix-required: rewrite to the dedicated skill-agent-ce-prefix.test.ts, narrow legacy set to lfg, drop the stale .agent.md snippet and foreign memory path. - compound-refresh-skill-improvements: mode:autofix -> mode:headless. - git-workflow state-machines: git-commit -> ce-commit naming + fix dead absolute-path links. - script-first-skill-architecture: reframe retired origin skill, re-anchor on ce-sessions, drop Node.js stance that conflicted with prefer-python. - pass-paths-not-content: add missing category field. Bootstrap CONCEPTS.md (beta skill, confidence anchor, autofix class) and surface it in AGENTS.md.
tmchow
added a commit
that referenced
this pull request
Jun 2, 2026
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.
CONCEPTS.md and its AGENTS.md discoverability line move to PR #838, which introduces the seeding skill change that produces the repo-wide glossary. This branch's copy predates that fix (the lumpy 3-entry version); dropping it here so it doesn't collide with #838 at merge. This PR now scopes to the skill-design learnings refresh.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 203f3e41d9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
changed the title
…ract The "Applied" historical record named the promoted beta `ce-code-review-beta`, a plausible-but-wrong reconstruction. The actual legacy artifact in the cleanup registry/tests (src/utils/legacy-cleanup.ts, tests/cli.test.ts) is `ce-review-beta` / `ce:review-beta`. Using the real name keeps the doc from sending maintainers to validate the wrong legacy skill. Left beta-skills-framework.md's `ce-code-review-beta` untouched — that's a hypothetical convention example, not a historical record.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
ce-compound-refreshpass over thedocs/solutions/skill-design/cluster (14 docs): 12 updated, 2 kept. Plus a bootstrap ofCONCEPTS.md.This is doc-accuracy maintenance — no behavior changes. Each doc was investigated against the current codebase before editing.
Why
The skill-design learnings had drifted from the code in one dominant way: the
ce:colon →ce-hyphen skill-naming convention (now test-enforced) was never propagated into the older docs, and the doc-review persona agents moved fromagents/document-review/*.agent.mdto flatagents/ce-*-reviewer.md. Several docs also carried concrete factual drift.Highlights
ce:→ce-,ce:review→ce-code-review, agent paths to flatce-*-reviewer.md).confidence-anchored-scoringas canonical, kept the still-valid structural synthesis patterns.slfg/report-onlyflag (onlylfg/autofixis actually enforced).tests/skill-agent-ce-prefix.test.ts, the narrowed legacy set (lfgonly), flat.mdagents, and removal of a foreign-machine memory path.mode:autofix→mode:headless(token renamed since the doc was written).git-commit→ce-commitnaming and fixed two dead absolute-path links.ce-sessions, dropped a Node.js language stance that conflicted with the prefer-python learning.categoryfield.A consolidation of
beta-promotion-orchestration-contractwas considered but reverted: the pre-delete inbound-link check found 13 substantive citations, marking it as a doc with high standalone retrieval value.CONCEPTS.md (new)
Bootstrapped the project glossary with three well-attested, project-specific terms: beta skill, confidence anchor, autofix class. Surfaced in
AGENTS.mdso it's discoverable. More entries will accrete as future refresh runs cover other scopes.Scope note
Only the
skill-design/cluster was processed this run. The remaining 16 solutions docs (root,best-practices/,developer-experience/,integrations/,workflow/) are untouched and can be refreshed in a follow-up.Validation
All 12 edited docs pass frontmatter parser-safety validation. No code or test changes.