Summary

The docs/solutions/ knowledge store only compounds value when agents can find it. Today, only plugin-mediated workflows (ce:plan via learnings-researcher) know to search there. Agents in fresh sessions, other tools (Cursor, Copilot), or collaborators without the plugin have no reason to discover it.

Both ce:compound and ce:compound-refresh now run a discoverability check after their main work completes. If the project's instruction file (AGENTS.md or CLAUDE.md) doesn't surface the knowledge store to agents, the skill suggests a minimal addition — with consent before editing.

What gets added

The addition adapts to the AGENTS.md/CLAUDE.md's existing structure. Two examples from testing:

When AGENTS.md/CLAUDE.md has a directory listing or architecture section — a single line is added:

app/
  models/        # ActiveRecord models
  controllers/   # Request handling
  views/         # ERB templates
docs/
  solutions/     # Documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type)

When AGENTS.md/CLAUDE.md has a documentation section with bullet entries — a bullet is added:

## Documentation

- `docs/adr/` — Architecture Decision Records
- `docs/api/` — OpenAPI specs (auto-generated from code annotations)
- `docs/runbooks/` — Incident response procedures
- `docs/solutions/` — Searchable knowledge store of previously solved problems, organized by category with YAML frontmatter (`module`, `tags`, `problem_type`); relevant when implementing or debugging in documented areas

When AGENTS.md/CLAUDE.md is flat with no sections — a line is appended matching the existing style:

Use `bun test` to run tests.
Prefer Tailwind utility classes over custom CSS.
This is a Next.js 14 app with App Router.
`docs/solutions/` contains categorized write-ups (YAML frontmatter with tags, problem_type, component) of past bugs and decisions, relevant when implementing or debugging in documented areas.

The tone is always informational ("relevant when...") rather than imperative ("check before...") to avoid redundant reads when the plugin's own workflows already search docs/solutions/.

Key decisions

• Semantic assessment, not string matching. The check evaluates whether an agent reading the file would learn three things: (1) the store exists, (2) enough about its structure to search effectively, (3) when it's relevant. The file could express this many different ways without ever using the literal path docs/solutions/.
• Shim detection. One file may just @-include the other (e.g., CLAUDE.md containing only @AGENTS.md). The check identifies which file holds substantive content and targets that one.
• Prefer existing sections. The skill strongly prefers adding a single line to an existing architecture/directory/documentation section over creating a new headed section.
• Consent-gated editing. In interactive modes, explains why discoverability matters and uses the platform's question tool to get user approval. In autofix mode (compound-refresh), includes a report recommendation without editing.

Test plan

• Tested across 12 fixture scenarios covering: shim files (both directions), directory listings, flat files, files that already mention the store, files that mention the path but not the spirit, files using different terminology, minimal files, complex multi-section files, no files, and both-files-substantive
• Ran 2 iterations — iteration 1 identified imperative tone and unnecessary new-section creation, iteration 2 confirmed fixes landed (7/7 tone issues resolved, 3/3 section issues resolved)

🤖 Generated with Claude Opus 4.6 (1M context) via Claude Code