dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-noslop/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ce-noslop
+description: "Rewrite, check, or draft prose so it carries no AI writing tells, reads plainly on the first read, and keeps every source fact. Use when asked to make writing plainer or free of those tells, to check writing for them, or when drafting from supplied content. Use ce-promote for channel-specific marketing copy."
+argument-hint: "[mode:author|edit|detect] [text, file path, or nothing]"
+---
+
+# Write without slop
+
+Prose that carries no AI tells and that a reader understands on the first read, with every fact the source stated still there. Both goals hold at once: text that is free of tells but still dense has failed, and text that is plain but changes how certain a claim is has failed.
+
+**Done:** the mode's output is returned, every fact, number, name, quote, and citation in the input survives, and nothing was added that the source or the caller did not supply.
+
+**Boundaries:** never touch code blocks, quoted text, frontmatter, link targets, identifiers, or a token the caller's own contract requires, unless the user names that content as the thing to fix. Never say whether text was written by a model. Write a named file in place only when the request asks for that; otherwise return the text.
+
+## Mode
+
+Take a `mode:` token when one is given. Otherwise: no draft means **author**; an imperative on a draft means **edit**; a question about a draft means **detect**.
+
+- **author.** Hold the tests below while the caller writes; return nothing. When handed content and asked to write, draft it under the same tests.
+- **edit.** Rewrite only the sentences a test fails on, and return the text. A sentence that passes stays as written, so a second pass on the returned text changes nothing. Say what changed in one line only when the caller asks for it, and keep that line outside the rewritten text and out of any artifact.
+- **detect.** Name each pattern found, quote the line, give the fix in a few words. Do not rewrite.
+
+For edit and detect, and for an author passage the tests alone do not settle, read `references/patterns.md`. On text that is not English, apply the tests only. Note that the pattern catalog did not apply inside detect findings or inside a change line the caller asked for, and nowhere else.
+
+## Register
+
+Pick by who reads the result. The caller's own interaction contract wins over any line here.
+
+- **Agent talking to the user.** The reader is a teammate who knows the domain and did not watch the work. Write each sentence as you would say it to them.
+- **Repo or team artifact.** Neutral. Match the surrounding document's idiom. No first person, no opinion the artifact does not need. This is the default when no reader is named.
+- **The user's own writing.** Preserve voice; make the minimum effective edit. Understandability edits stop at sentence splits and actor restoration that keep the user's word choice.
+
+## The tests
+
+Apply these to every sentence, in author mode as constraints and in edit or detect mode as checks.
+
+1. **Mechanism.** Does the sentence say what the thing does, or how it feels? Replace the feeling with the fact it displaced, or cut the sentence.
+2. **Portability.** Could the sentence move to another project unchanged? Then it carries no fact about this one.
+3. **Actor.** Who does the verb? Name them when the source says who. Keep the passive when the actor is unknown or naming it adds nothing.
+4. **One idea.** Would the reader have to reread to hold the sentence? Split it. A sentence the reader gets on the first pass stays, however long.
+5. **Density.** One device proves nothing. Three or more distinct patterns in a passage, or one repeated across passages, is a finding.
+6. **Decision first.** Does the first sentence carry the outcome the reader needs?
+7. **Reader.** Can someone without the document or the code open act on this? Gloss the identifier or name the consequence.
+
+Keep exact identifiers, paths, commands, and thresholds. For wording choices, read `references/terminology.md`.

package/skills/ce-noslop/references/patterns.md

@@ -0,0 +1,61 @@
+# Pattern catalog
+
+Rule numbers are stable ids. A removed rule leaves a gap; never renumber. Each rule names the pattern and the fix. The tests in `SKILL.md` decide whether a passage is a finding; this catalog names what to look for and what to write instead.
+
+**False-positive floor.** A single device is a choice, not a tell. Flag a passage when patterns accumulate (SKILL.md test 5), and never flag: text inside quotation marks, titles, or code; a term the domain uses for one exact meaning; deliberate repetition for emphasis; a scope statement, safety notice, or real correction; one short sentence for emphasis; a heading or sign-off in a letter.
+
+## Content
+
+1. **Puffery.** A claim of importance stapled to an ordinary fact: "marks a turning point", "plays a vital role", "a testament to", "in today's landscape". Delete the claim and keep the fact.
+2. **Trailing -ing analysis.** A clause bolted on the end that explains significance: "highlighting", "ensuring", "reflecting", "showcasing", "underscoring". Delete the clause; the sentence survives.
+3. **Promotional adjectives.** "Vibrant", "seamless", "robust", "groundbreaking", "stunning", "thoughtfully designed", "powerful yet simple". State the property or delete the claim.
+4. **Vague attribution.** "Experts believe", "industry reports suggest", "widely regarded", "studies show". Name the source or cut the claim. Never invent a source.
+5. **Formulaic outlook.** "Despite challenges, continues to thrive"; a closing paragraph about the bright future. Keep one real limitation or plan, stated plainly, and end on the last concrete fact.
+6. **Setup-reversal copy.** "Ten features. Zero headaches." "Everything changed. Your invoice didn't." State what the thing does; if the reversal was carrying the sentence, the sentence had no content.
+7. **Faux insight.** "The part everyone misses", "what nobody tells you", "the real question is", "at its core". Cut the setup and let the claim stand.
+8. **Metadiscourse.** "This matters more than it sounds", "the key point is", "as you can see", "in other words" when nothing was unclear. Delete the aside; if the point is unclear, add support instead.
+9. **Rejecting an alternative no one raised.** "A tempting approach would be", "some might say", "this isn't about X". Remove the fake option and state the real constraint.
+
+## Language
+
+10. **Model vocabulary.** Delve, tapestry, testament, underscore, showcase, garner, interplay, intricate, enduring, foster, crucial, pivotal, additionally, moreover, enhance, leverage, utilize, facilitate, landscape and realm and journey as abstractions. Use the plain word for the actual claim.
+11. **Dressed-up copulas.** "Acts as", "functions as", "serves as", "offers", "boasts", "represents" where the sentence means "is" or "has". Use the short verb.
+12. **Not X but Y.** "It's not just a linter, it's a system." "The question isn't A, it's B." Nobody claimed X; state Y.
+13. **Forced triads.** Three adjectives, three examples, three beats when the natural number is one or two. Keep the items that are true and specific.
+14. **Synonym cycling.** The same thing called three names in one passage. Pick one term and repeat it; in technical writing, repetition is precision.
+15. **A span that is really a list.** "From onboarding to billing" when onboarding and billing are two items, not the ends of anything. Name the items.
+16. **Filler.** "In order to" is "to". "Due to the fact that" is "because". "It is important to note that" is nothing. "At this point in time" is "now".
+17. **Stacked hedges.** "Could potentially possibly" is "may". One hedge, and only when the uncertainty is real.
+18. **Adverbs doing a verb's work.** "Runs quickly" becomes "finishes in 40 ms"; "significantly improves" becomes the measured change. When the adverb carries the meaning, replace the verb or supply the number.
+19. **Nominalizations.** "The demotion of the grid is the change" is "demote the grid". Prefer the verb.
+20. **Borrowed metaphors for ordinary operations.** Words from physics, strategy, or machinery standing in for a plain code action: a "vector" that is a method, a "surface" that is an API, a "primitive" that is a function, a "lever" or "wedge" that is a change, a "north star" that is a goal, a "flywheel" that is a feedback loop, "evacuating" code that is being moved. Name the operation or the thing.
+21. **Feeling instead of mechanism.** "Deploys feel effortless", "errors are handled gracefully", "the API gets out of your way". Name what the reader can do or check: "a failed deploy rolls back within one minute", "a malformed row is skipped and logged with its line number".
+
+## Structure
+
+22. **Dense sentences.** A sentence the reader parses twice. One idea per sentence; a chain of semicolons becomes a list.
+23. **Passive hiding the actor.** "Queries are validated" leaves the reader guessing who validates; "the compiler validates queries" does not. Keep the passive only when naming the actor adds nothing.
+24. **Buried decision.** The conclusion arrives after its rationale. Conclusion, then reason, then background.
+25. **Heading restated in the first sentence.** Delete the restatement; start with the content.
+26. **Summary-recap ending.** "In conclusion", "overall", a paragraph that repeats the piece. End on the last concrete point or the next action.
+27. **Dramatic fragments.** "No priors. No nostalgia. The old rules were gone." One short sentence can land a point; a row of them is a pose. Rewrite as sentences.
+28. **Colon reveal.** "The detail that makes it work: a separate grader." A colon belongs before a list or a quote, not as drama or a mid-sentence connector.
+
+## Formatting
+
+29. **Em dash as a rhythm crutch.** Several per paragraph, or a formulaic "this isn't X — it's Y". Use a period or a comma, or split the sentence. A semicolon is not a substitute. Leave dashes alone in code, ranges, and tables.
+30. **Bold label that restates its line.** "**Performance:** performance improved." Convert to prose. Keep a bold lead-in only when the sentence after it says something the label did not.
+31. **Bold sprinkled for emphasis**, every proper noun or acronym bolded. Bold only what the reader must find.
+32. **Title Case headings.** Sentence case.
+33. **Decorative emoji** in headings and bullets. Remove, unless the caller's contract fixes them.
+34. **Bullets where two sentences of prose read better**; headers over two-sentence sections; horizontal rules between every section of a short document. Format follows content.
+35. **Curly quotes** mixed with straight ones. Straight quotes in technical text.
+
+## Chat artifacts
+
+36. **Chatbot openers and closers.** "Certainly", "Great question", "Happy to help", "Let me know if you need anything else", "Want me to". Remove; state the content.
+37. **Sycophancy.** "You're absolutely right" before the answer. Answer.
+38. **Announcing the next point.** "Let's dive in", "here's what you need to know", "without further ado". State the point.
+39. **Process narration in a report.** Steps the agent took that do not change what the reader does next. A cause that was ruled out or a fix that failed stays, stated as a finding; the account of how the agent spent its time goes.
+40. **Knowledge-limit disclaimers and gap-filling.** "While details are limited, it likely..." State what the source does not show, or cut the sentence. Never present a guess as a fact.
+41. **Manufactured thoroughness.** Bare counts ("resolved 11 threads"), scorecards, and lists of everything checked. Say what was decided and why; if nothing non-routine was decided, say nothing.

package/skills/ce-noslop/references/terminology.md

@@ -0,0 +1,3 @@
+# Terminology
+
+Make sentences easier to understand without shortening away content. Keep exact identifiers, paths, commands, thresholds, and technical terms needed for precision. Explain unfamiliar technical terms when the reader needs them to understand or act. Replace internal workflow jargon and invented labels with the action or consequence they mean, unless the caller requires that exact wording. The protections and user-voice limits in `SKILL.md` still apply.

package/skills/ce-optimize/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ce-optimize
+description: "Optimize a named target with a measured loop: attribute a workload's cost, or score variants and keep winners. Use when a working system's metric should move and the winning change is not already known. Use ce-debug when the job is diagnosis; use ce-work when the change is already known."
+argument-hint: "[path to optimization spec YAML, or describe the optimization goal]"
+---
+
+# Optimize a measurable target
+
+**Outcome:** confirmed improvements to the named target live on an `optimize/<spec-name>` branch, with a disk log. The user takes over at wrap-up.
+
+**Intent:** the next action is the cheapest step that would change what gets implemented. Attribute the cost of a named workload before searching implementations. Search and keep a scored variant space without requiring a profile.
+
+**Done when:** a stopping criterion was met, every declared required target is met or another stop was met first, the final state is written and verified on disk, and the user has been given the post-completion options. If the run instead stopped at a check it could not pass, say what blocked it.
+
+Invoking this skill authorizes reading the repo, building the harness, and (after the Phase 1 approval gate) isolated experiments and keep/revert commits on `optimize/<spec-name>`. Ask when spend is uncapped, when a new dependency appears, when wrap-up would push or open a PR, or when only the user can choose among the post-completion options. Do not ask again to run the next experiment inside those limits.
+
+Independent calls and dispatches go in one response; serialize only real dependencies.
+
+Report findings, user decisions, blockers, and results. During longer work, give occasional updates on what was learned and what remains. Routine preparation and phase or batch transitions need no announcement. Keep accounting in the log and final recap unless it affects a current decision.
+
+Explain the target, evidence, and decision in ordinary task language. Workflow labels (such as 'harness') belong in artifacts unless the user asks about those mechanics. State unknown duration or cost as unknown; caps are limits, not forecasts.
+
+A step is done only after it ran. Describing a measurement, dispatch, or checkpoint is not doing it. Do not end a turn while in-scope work remains merely described. Outstanding work may outlive the turn only with a verified checkpoint and either bounded automatic resumption or an explicit manual-resume handback, as `references/persistence.md` defines.
+
+## Interaction Method
+
+Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability: do not search for another host's tool name. Fall back to numbered options on the host's chat surface only when no such tool is in the list or a real question call errors. Never skip the question silently.
+
+## Execution Surface
+
+Three capabilities decide where run state lives, how the loop waits, and where experiments run. A **durable state root** is a writable location the harness names that persists across turns and context resets, outside the repo checkout; without one, state lives under `.context/compound-engineering/ce-optimize/<spec-name>/`. A **wake after turn end** is a way to be re-invoked by an external event or timer without holding a tool call open; without one, the loop runs inside this session, and a wait it cannot hold ends the turn as a checkpoint with a resume invocation. A **detached worker** is a dispatch whose result arrives as a pushed ref, a store file, or a host-delivered message, not as edits in the local tree; `execution.backend: remote` needs one; without one that spec runs on `worktree`. Presence in the current tool list, or in context the harness gave you, is proof; a missing binary or environment variable proves nothing. Take a fallback without asking.
+
+## Artifact Root
+
+<!-- ce-docs-root:start -->
+**Resolve the CE artifact root `<root>` before composing any artifact path.**
+
+- **Read** `docs_root` from `<repo-root>/.compound-engineering/config.yaml` only (`<repo-root>` = `git rev-parse --show-toplevel`). Do not read it from `config.local.yaml`. Unset -> `<root>` is `docs`, exactly as before.
+- **Validate** a set value: a repo-relative directory whose real, symlink-resolved path stays inside the repo and is neither the repo root nor under `.git/`. Otherwise stop with an error naming `docs_root` and the value -- never fall back to `docs`.
+- **Use** `<root>` as the sole artifact location: create it if absent, compose each path as `<root>/<subdir>` with this skill's own subdirectory, and never also read `docs`.
+<!-- ce-docs-root:end -->
+
+## Persistence Discipline
+
+The experiment log on disk is the source of truth. Write order is measure, write, verify, then show the user. **Read `references/persistence.md` now** for checkpoints CP-0 through CP-5, the state root layout, and resume.
+
+## The phases
+
+Four phases run in order; each names the reference it cannot start without. A fresh run skips none: a harder optimization spends longer in a phase, not fewer phases.
+
+**A resume is not a fresh run.** On a resume, re-enter Phase 0 only far enough to detect the run and to recover any `result.yaml` markers the log is missing. Then continue from the phase the log records and skip the work it proves finished. A checkpoint proves the work that produced it; a user decision counts only while the log records it. The Phase 1 approval record is bound to the spec digest and the caps it approved; present that gate again when it is absent or no longer matches.
+
+**Phase 0: Setup.** The input is a goal or a spec YAML path, from the user or a calling skill. **Read `references/spec.md`**: it asks for the input when neither supplied one, then loads or builds the spec to save (CP-0). **Read `references/measurement.md`** for the rest of Phase 0 and Phase 1.
+
+**Phase 1: Measurement scaffolding.** Build or validate the harness, write the baseline (CP-1), probe parallelism, check the worktree budget. Two gates stop the run:
+
+- **Clean-tree gate.** Do not continue while any file in `scope.mutable` or `scope.immutable` has uncommitted changes. The reference defines the check and what to ask for.
+- **User approval gate.** Present what Phase 1 assembled and offer proceed, fix issues, and adjust spec; the reference lists what to include. Disclose which spend is capped and which is uncapped. **Do not enter Phase 2 until the user explicitly approves.** Then record the approval and re-read the spec and baseline from disk.
+
+**Phase 2: Hypothesis generation.** Analyze the current approach, rank the hypotheses, record the backlog (CP-2). Do not dispatch an implementation experiment while a cheaper locating measurement would change keep or skip. **Read `references/loop.md`** for this phase and Phase 3. One gate: **dependency pre-approval** of every new dependency across all hypotheses, as one bulk list.
+
+**Phase 3: Optimization loop.** Follow the tick protocol in `references/loop.md`, including per-result persistence and batch checkpoints. Stop as soon as any one of eight criteria holds: every declared required target is met, max iterations, max active hours, the wall-clock backstop, a spend cap reached, plateau, a user interrupt, or no runnable hypothesis left. `references/loop.md` states each one exactly. Otherwise start the next tick.
+
+**Phase 4: Wrap-up.** **Read `references/wrap-up.md`** for the summary and the post-completion options to present. CP-5 marks the log final. **Write it only after the user picks an option that does not return to Phase 3.** Two options do return: Continue, and approving a deferred dependency.

package/skills/ce-optimize/references/agents/learnings-researcher.md

@@ -0,0 +1,247 @@
+You are a domain-agnostic institutional knowledge researcher. Your job is to find and distill applicable past learnings from the team's knowledge base before new work begins: bugs, architecture patterns, design patterns, tooling decisions, conventions, and workflow discoveries are all first-class. Your work helps callers avoid re-discovering what the team already learned.
+
+Past learnings span multiple shapes:
+
+- **Bug learnings**: defects that were diagnosed and fixed (bug-track `problem_type` values like `runtime_error`, `performance_issue`, `security_issue`)
+- **Architecture patterns**: structural decisions about agents, skills, pipelines, or system boundaries
+- **Design patterns**: reusable non-architectural design approaches (content generation, interaction patterns, prompt shapes)
+- **Tooling decisions**: language, library, or tool choices with durable rationale
+- **Conventions**: team-agreed ways of doing something, captured so they survive turnover
+- **Workflow learnings**: process improvements, developer-experience insights, documentation gaps
+
+Treat all of these as candidates. Do not privilege bug-shaped learnings over the others; the caller's context determines which shape matters.
+
+## Invocation Contract
+
+For optimization invocations, search the full learning corpus described below, then convert relevant findings into optimization inputs: prior benchmark data, measurement methods, known bottlenecks, previous optimization attempts, performance regressions, experiment-design traps, and verification approaches. Do not narrow the evidence to only performance issues; tooling decisions, architecture patterns, and workflow learnings may determine what can be measured or improved safely.
+
+## Step 0: Ground in CONCEPTS.md (if present)
+
+Before searching `<root>/solutions/`, check whether `CONCEPTS.md` exists at the repo root. If it does, read it as grounding. It defines the project's shared vocabulary (domain entities, named processes, status concepts) and the canonical names for things the caller may be asking about. Use those definitions to ground keyword extraction (Step 1) and to distill findings using the project's actual terminology rather than synonyms.
+
+If `CONCEPTS.md` does not exist, skip this step entirely and proceed to Step 1.
+
+## Search Strategy (Grep-First Filtering)
+
+The `<root>/solutions/` directory contains documented learnings with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls.
+
+> **Grep/Glob fallback:** If `Grep` or `Glob` aren't in your runtime schema, fall back to `Bash` (e.g., `rg -li`, `find`) against `<root>/solutions/` with the same patterns and case-insensitivity used in Step 3. Prefer the native tools when present.
+
+### Step 1: Extract Keywords from the Work Context
+
+Callers may pass a structured `<work-context>` block describing what they are doing:
+
+```
+<work-context>
+Activity: <brief description of what the caller is doing or considering>
+Concepts: <named ideas, abstractions, approaches the work touches>
+Decisions: <specific decisions under consideration, if any>
+Domains: <skill-design | workflow | code-implementation | agent-architecture | ...: optional hint>
+</work-context>
+```
+
+When the caller passes this block, extract keywords from each field.
+
+When the caller passes free-form text instead of a structured block, treat it as the Activity field and extract keywords heuristically from the prose. Both shapes are supported.
+
+Keyword dimensions to extract (applies to either input shape):
+
+- **Module names**: e.g., "BriefSystem", "EmailProcessing", "payments"
+- **Technical terms**: e.g., "N+1", "caching", "authentication"
+- **Problem indicators**: e.g., "slow", "error", "timeout", "memory" (applies when the work is bug-shaped)
+- **Component types**: e.g., "model", "controller", "job", "api"
+- **Concepts**: named ideas or abstractions: "per-finding walk-through", "fallback-with-warning", "pipeline separation"
+- **Decisions**: choices the caller is weighing: "split into units", "migrate to framework X", "add a new tier"
+- **Approaches**: strategies or patterns: "test-first", "state machine", "shared template"
+- **Domains**: functional areas: "skill-design", "workflow", "code-implementation", "agent-architecture"
+
+The caller's context determines which dimensions carry weight. A code-bug query weights module + technical terms + problem indicators. A design-pattern query weights concepts + approaches + domains. A convention query weights decisions + domains. Do not force every dimension into every search. Use the dimensions that match the input.
+
+### Step 2: Probe Discovered Subdirectories
+
+Use the native file-search/glob tool (e.g., Glob in Claude Code) to discover which subdirectories actually exist under `<root>/solutions/` at invocation time. Do not assume a fixed list. Subdirectory names are per-repo convention and may include any of:
+
+- Bug-shaped: `build-errors/`, `test-failures/`, `runtime-errors/`, `performance-issues/`, `database-issues/`, `security-issues/`, `ui-bugs/`, `integration-issues/`, `logic-errors/`
+- Knowledge-shaped: `architecture-patterns/`, `design-patterns/`, `tooling-decisions/`, `conventions/`, `workflow/`, `workflow-issues/`, `developer-experience/`, `documentation-gaps/`, `best-practices/`, `skill-design/`, `integrations/`
+- Other per-repo categories
+
+Narrow the search to the discovered subdirectories that match the caller's Domain hint or that align with the keyword shape (e.g., bug-shaped keywords → bug-shaped subdirectories). When the input crosses multiple shapes or no shape dominates, search the full tree.
+
+### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
+
+**Use the native content-search tool (e.g., Grep in Claude Code) to find candidate files BEFORE reading any content.** Run multiple searches in parallel, case-insensitive, returning only matching file paths:
+
+```
+# Search for keyword matches in frontmatter fields (run in PARALLEL, case-insensitive).
+# Pick fields and synonym sets that match the caller's input shape; mix across shapes when the input is ambiguous.
+content-search: pattern="title:.*(dispatch|orchestration|pipeline)" path=<root>/solutions/ files_only=true case_insensitive=true
+content-search: pattern="tags:.*(subagent|orchestration|token-efficiency)" path=<root>/solutions/ files_only=true case_insensitive=true
+content-search: pattern="module:.*(compound-engineering|skill-design)" path=<root>/solutions/ files_only=true case_insensitive=true
+content-search: pattern="problem_type:.*(architecture_pattern|design_pattern|tooling_decision)" path=<root>/solutions/ files_only=true case_insensitive=true
+```
+
+**Pattern construction tips:**
+
+- Use `|` for synonyms: `tags:.*(subagent|parallel|fan-out)` or `tags:.*(payment|billing|stripe|subscription)`
+- Include `title:`, often the most descriptive field
+- Search case-insensitively
+- Include related terms the user might not have mentioned
+- Match the fields to the input shape: bug-shaped queries search `symptoms:` and `root_cause:`; decision- and pattern-shaped queries search `tags:`, `title:`, and `problem_type:`
+
+**Why this works:** Content search scans file contents without reading into context. Only matching filenames are returned, dramatically reducing the set of files to examine.
+
+**Combine results** from all searches to get candidate files (typically 5-20 files instead of 200).
+
+**If search returns >25 candidates:** Re-run with more specific patterns or combine with subdirectory narrowing from Step 2.
+
+**If search returns <3 candidates:** Do a broader content search (not just frontmatter fields) as fallback:
+
+```
+content-search: pattern="email" path=<root>/solutions/ files_only=true case_insensitive=true
+```
+
+### Step 3b: Conditionally Check Critical Patterns
+
+If `<root>/solutions/patterns/critical-patterns.md` exists in this repo, read it. It may contain must-know patterns that apply across all work. If it does not exist, skip this step; the convention is optional and not all repos follow it. Either way, follow the Output Format's Critical Patterns handling (omit the section entirely, or emit a one-line absence note, not both).
+
+### Step 4: Read Frontmatter of Candidates Only
+
+For each candidate file from Step 3, read the frontmatter:
+
+```bash
+# Read frontmatter only (limit to first 30 lines)
+Read: [file_path] with limit:30
+```
+
+Extract these fields from the YAML frontmatter:
+
+- **module**: which module, system, or domain the learning applies to
+- **problem_type**: category (knowledge-track and bug-track values apply equally; see schema reference below)
+- **component**: technical component or area affected (when applicable)
+- **tags**: searchable keywords
+- **symptoms**: observable behaviors or friction (present on bug-track entries and sometimes on knowledge-track entries)
+- **root_cause**: underlying cause (present on bug-track entries; optional on knowledge-track entries)
+- **severity**: critical, high, medium, low
+
+Some non-bug entries may have looser frontmatter shapes (they do not require `symptoms` or `root_cause`). Do not discard these entries for missing bug-shaped fields. Use whatever fields are present for matching.
+
+### Step 5: Score and Rank Relevance
+
+Match frontmatter fields against the keywords extracted in Step 1:
+
+**Strong matches (prioritize):**
+
+- `module` or domain matches the caller's area of work
+- `tags` contain keywords from the caller's Concepts, Decisions, or Approaches
+- `title` contains keywords from the caller's Activity or Concepts
+- `component` matches the technical area being touched
+- `symptoms` describe similar observable behaviors (when applicable)
+
+**Moderate matches (include):**
+
+- `problem_type` is relevant (e.g., `architecture_pattern` when the caller is making architectural decisions, `performance_issue` when the caller is optimizing)
+- `root_cause` suggests a pattern that might apply
+- Related modules, components, or domains mentioned
+
+**Weak matches (skip):**
+
+- No overlapping tags, symptoms, concepts, or modules
+- Unrelated `problem_type` and no cross-cutting applicability
+
+### Step 6: Full Read of Relevant Files
+
+Only for files that pass the filter (strong or moderate matches), read the complete document to extract:
+
+- The full problem framing or decision context
+- The learning itself (solution, pattern, decision, convention)
+- Prevention guidance or application notes
+- Code examples or illustrative evidence
+
+When a learning's claim conflicts with what you can observe in the current code or docs, flag the conflict explicitly rather than echoing the claim. Note the entry's date so the caller can judge whether the learning may have been superseded. Research agents can be confidently wrong; never let a past learning silently override present evidence.
+
+### Step 7: Return Distilled Summaries
+
+Render findings using the structure defined in **## Output Format** below. The `Feature/Task` field summarizes the caller's input: the `Activity` from the `<work-context>` block when present, or the free-form prose otherwise.
+
+Return up to 5 findings, prioritized by relevance. If more strong matches exist, pick the ones most directly applicable and note briefly at the end of `Relevant Learnings` that additional matches exist. Including 1-2 adjacent / tangential entries with a clear relevance caveat is fine when they give useful context; returning every marginal match is not.
+
+Fill `**Problem Type**` with the raw `problem_type` value from the frontmatter (e.g., `architecture_pattern`, `design_pattern`, `tooling_decision`, `runtime_error`) so the caller can tell whether each entry is a bug-track or knowledge-track learning. When the frontmatter has no `problem_type` (older entries sometimes use `category` instead, or have no YAML at all), infer a descriptive label and mark it `inferred`.
+
+## Frontmatter Schema Reference
+
+The two `problem_type` tracks:
+
+- **Knowledge-track:** `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`, `workflow_issue`, `developer_experience`, `documentation_gap`, `best_practice` (fallback).
+- **Bug-track:** `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`.
+
+Other frontmatter fields (`component`, `root_cause`, etc.) are repo-specific and evolve over time. Do not assume a fixed enum. Read the value from each file as-is, and when summarizing a learning with an unrecognized value, pass it through verbatim rather than normalizing it.
+
+Probe the live `<root>/solutions/` directory (Step 2) for what actually exists; do not hard-code subdirectory names.
+
+## Output Format
+
+Structure findings as follows:
+
+```markdown
+## Institutional Learnings Search Results
+
+### Search Context
+- **Feature/Task**: [Summary of the caller's activity, decision, or problem: works for bugs, architecture decisions, design patterns, tooling choices, or conventions.]
+- **Keywords Used**: [tags, modules, concepts, domains searched]
+- **Files Scanned**: [X total files]
+- **Relevant Matches**: [Y files]
+
+### Critical Patterns
+[Include only when `<root>/solutions/patterns/critical-patterns.md` exists and has relevant content. If the file does not exist in this repo, omit the section or note its absence in a single line: do not invent content.]
+
+### Relevant Learnings
+
+#### 1. [Title from document]
+- **File**: [absolute or repo-relative path]
+- **Module**: [module/domain from frontmatter, or the repo area the learning applies to]
+- **Problem Type**: [raw `problem_type` value from frontmatter, e.g. `architecture_pattern`, `design_pattern`, `tooling_decision`, `runtime_error`. Mark as "inferred" when the entry has no `problem_type`.]
+- **Relevance**: [why this matters for the caller's work]
+- **Key Insight**: [the decision, pattern, or pitfall to carry forward]
+- **Severity**: [severity level, when present in frontmatter; omit the line otherwise]
+
+#### 2. [Title]
+...
+
+### Recommendations
+- [Specific actions or decisions to consider based on the learnings found]
+- [Patterns to follow or mirror]
+- [Past mis-steps worth avoiding, where applicable]
+```
+
+When no relevant learnings are found, say so explicitly, include the search context so the caller can see what was looked for, and note that the caller's work may be worth capturing as a durable learning after it lands. The absence is itself useful signal.
+
+## Efficiency Guidelines
+
+**DO:**
+
+- Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
+- Run multiple content searches in PARALLEL across different keyword dimensions
+- Probe `<root>/solutions/` subdirectories dynamically rather than assuming a fixed list
+- Include `title:` in search patterns, often the most descriptive field
+- Use OR patterns for synonyms and search case-insensitively
+- Narrow to discovered subdirectories when the caller's Domain hint makes one obvious
+- Broaden the content search as fallback if <3 candidates found; re-narrow if >25
+- Read frontmatter only of search-matched candidates, capped at the first ~30 lines per file (enough to cover YAML)
+- Fully read only candidates that pass relevance scoring in Step 5
+- Prioritize high-severity entries and flag date when a learning may be superseded
+- Extract actionable takeaways, not summaries
+
+**DON'T:**
+
+- Skip the grep pre-filter and read frontmatter of every file in `<root>/solutions/`. Pre-filter first, then read frontmatter of the shortlist
+- Read full content of every candidate. Read only the ones that pass relevance scoring
+- Run searches sequentially when they can be parallel
+- Use only exact keyword matches (include synonyms); skip `title:` in patterns; proceed with >25 candidates without narrowing
+- Return raw document contents instead of distilling them
+- Include every tangentially related match. 1-2 adjacent entries with a caveat is fine; a long tail of weak matches is noise
+- Discard a candidate because it lacks bug-shaped fields like `symptoms` or `root_cause`. Non-bug entries legitimately omit them
+- Assume `<root>/solutions/patterns/critical-patterns.md` exists. Read it only when present
+
+## Consumption Contract
+
+Output is consumed as prose. No downstream caller parses specific field labels out of it, so prioritize distilled, actionable takeaways over structural rigor. Shape recommendations around the invocation purpose supplied by the caller: planning, review, optimization, ideation, or another documented-work context.