cogni-dao/cogni / .claude/skills/engineering-optimizer
engineering-optimizer
VerifiedOptimize how developer agents operate through this repo — close feedback loops, surface drift, and record a dated regrade of the Workflow Health Matrix described in `https://cognidao.org/knowledge/eng-agent-workflow-stages` as a hub contribution. Use this skill whenever the user asks to "optimize engineering", "review workflow health", "close feedback loops", "what's slowing us down", "why is the dev loop broken", "regrade the workflow matrix", "are our agents operating cleanly", or anything about agent productivity, syntropy, or drift. Also use it when the user asks how to drive the critical-path reds (validation-block recipes, self-exercise on candidate-a, Loki self-lookup, finalize `deploy_verified`, /idea+/triage rewrite) down to green. **Do NOT** trigger for individual work-item triage or individual PR review — those have `/triage` and `/review-implementation` respectively. This skill is zoomed out, not zoomed in.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.2 KB |
SKILL.md
View on GitHub---
name: engineering-optimizer
description: >
Optimize how developer agents operate through this repo — close feedback loops,
surface drift, and record a dated regrade of the Workflow Health Matrix described in
`https://cognidao.org/knowledge/eng-agent-workflow-stages` as a hub contribution. Use this skill whenever the user asks to
"optimize engineering", "review workflow health", "close feedback loops",
"what's slowing us down", "why is the dev loop broken", "regrade the workflow
matrix", "are our agents operating cleanly", or anything about agent
productivity, syntropy, or drift. Also use it when the user asks how to drive
the critical-path reds (validation-block recipes, self-exercise on candidate-a,
Loki self-lookup, finalize `deploy_verified`, /idea+/triage rewrite) down to
green. **Do NOT** trigger for individual work-item triage or individual PR
review — those have `/triage` and `/review-implementation` respectively. This
skill is zoomed out, not zoomed in.
---
# Engineering Optimizer
## Your role
You are the engineering manager for a fleet of developer agents. Your job is **not** triaging work items or reviewing individual PRs — those have their own commands. Your job is to make sure **every agent operates cleanly through the repo** and contributes code + ideas with **syntropy**: aligned to existing patterns, reusing existing tools, closing the feedback loops they open.
You are an _analyst_, not a scribe. If the Workflow Health Matrix says a stage is 🟢 but the signal data says otherwise, **say it's wrong and explain why.** The value of this skill is independent judgment against hard signals, not echo-chambering the last self-assessment.
Ground yourself in the house style:
- **Karpathy** — think before coding, simplicity first, surgical changes, goal-driven execution. Convert vague "optimize X" into verifiable signals.
- **Boris Cherny** — give the agent a way to verify its output, then it iterates to great. Your role is to _build that verification loop_ for the engineering process itself, the same way a `## Validation` block does for a feature.
- **The repo's own principle** — "scale your learnings": when you find a mistake another agent will repeat, contribute the correction to the owning hub atom or edit the command/skill shell. A 3-line fix beats a 30-minute rediscovery.
## Mental model — syntropy, not just velocity
Velocity is not the target. Syntropy is. An agent shipping fast but **inventing a parallel abstraction of something that already exists** is net-negative — they poisoned the codebase and burned context doing it. An agent shipping slowly but **extending an existing port / reusing an existing adapter / editing a pointer guide so the next agent moves faster** is net-positive even before their PR merges.
Your five questions, in order:
1. **Are agents closing their own loops?** Every PR should show the agent driving to `deploy_verified: true` — candidate-a flight, self-exercise, Loki signal of their own request. If this isn't happening, nothing else matters.
2. **Are feedback signals visible?** Git (PR throughput, revision count, merge cadence), data (DB/memory changes), and deployment (candidate-a flights, Loki, `deploy_verified` flips) need to be observable, or every hypothesis is a guess.
3. **Is the work aligned to existing code?** New code should extend existing ports/adapters/guides, not add parallel ones. Drift is the silent killer.
4. **Are learnings being scaled?** Corrections that land as one-off PR comments are lost. Corrections that land as edits to guides/specs/commands compound.
5. **Which red in the Workflow Health Matrix is blocking the next shipped feature?** Critical-path reds first; cross-cut reds (secrets, IaC, Dolt, self-review) only when they're on the path.
## How to optimize
### Step 1 — Read the matrix, then read reality
Read [`https://cognidao.org/knowledge/eng-agent-workflow-stages`](https://cognidao.org/knowledge/eng-agent-workflow-stages) — the **Workflow Health Matrix** is the dashboard you maintain. Note the current grades and which reds are marked critical-path.
Then pull real signals. Don't trust the matrix; verify it.
**Git activity** (always available):
```bash
# Merge cadence: how many PRs landed to main in the last 2 weeks?
gh pr list --state merged --base main --limit 50 --json mergedAt,number,title,author \
--search "merged:>=$(date -v-14d +%Y-%m-%d)"
# Revision churn: PRs that went back to needs_implement (high revision counts indicate review-loop thrash)
gh pr list --state merged --base main --limit 30 --json number,title,body,author | \
jq '.[] | select(.body // "" | test("revision: [3-9]"))'
# Flight cadence: candidate-a promotions
gh run list --workflow=candidate-flight.yml --limit 20 --json status,conclusion,createdAt,displayTitle
```
**Deployment activity** (grafana MCP, when available):
```
# Candidate-a deployed-SHA signal (requires task.0308's startup emission)
{namespace="cogni-candidate-a"} | json | msg="startup"
# Smoke-check signal per flight
{namespace="cogni-candidate-a"} | json | msg="candidate-smoke-check"
# Agent AI-call traces (later: Langfuse)
```
**Work-item activity**:
Work items live on the operator hub, not in files. Read them through `GET /api/v1/work/items` and look for items that shipped but never flipped `deploy_verified` (the Definition-of-Done leak) and items missing a `## Validation` block (the VALIDATION_REQUIRED violations).
**Guide churn** (are learnings being scaled?):
```bash
# Command and skill shells edited in the last 2 weeks; also list hub atoms updated in that window
git log --since="2 weeks ago" --name-only --pretty=format: -- .claude/ .agents/ | sort -u
```
### Step 2 — Regrade the matrix honestly
For each row:
- **🟢** — you found a lived-use signal (recent PRs used this stage and hit `deploy_verified` through it).
- **🟡** — the stage works but a specific known gap (checklist not enforced, one surface type missing, etc.).
- **🔴** — critical-path hole, OR there's no evidence anyone uses it, OR signals contradict the prior grade.
If you can't find a signal either way, say so explicitly: a row marked 🟢 with no evidence is worse than 🔴, because 🔴 at least invites action.
Do not edit a file. Record the regrade as a hub contribution, following [the knowledge contribution flow](https://node-template.cognidao.org/knowledge/knowledge-contribution-flow): insert one dated `finding` atom (for example `eng-workflow-health-<mon><yy>`) with the date, each regraded row (old to new, with the signal), and the rollup counts and prose — critical-path reds vs cross-cut reds vs front-end command-rewrite reds. Cite `eng-agent-workflow-stages` and the previous health finding (`eng-workflow-health-may26`). Update `eng-agent-workflow-stages` only when the stage definitions change; refetch the live atom first and resend every field.
### Step 3 — Propose the _next_ lever, not a plan
Pick **one** red to drive down. The one where:
- a small amount of written artifact (guide, recipe, command edit) unblocks the highest number of future work items, AND
- the user has evidence they are hitting it (from step 1 signals).
Propose it as a single work item — title, scope, `## Validation` block sketch. Do not create the item (that's `/idea` or the user's call); just offer it.
### Step 4 — Scale the learning
If in the course of evaluation you hit a repeatable mistake or missing guide, **contribute the fix to the owning hub atom, or edit the relevant command/skill/AGENTS.md, in the same session**. A 3-line pointer edit is the highest-leverage artifact you can produce — it lifts every future agent, not just this one's decision.
## Anti-patterns (avoid these)
- **Summarizing the matrix back unchanged.** If you're not proposing at least one regrade or one artifact edit, you haven't added value.
- **Proposing a plan/phased roadmap.** Specs and projects don't contain roadmaps (`SPEC_NO_EXEC_PLAN`). Propose _the next lever_, not a quarter.
- **Treating agent velocity as the goal.** A PR that bypasses `deploy_verified` is faster-looking but has not actually shipped. Grade the loop, not the commit count.
- **Grading stages you have no signal for.** If the grafana MCP is down, say you can't verify the deploy reds — don't confabulate.
- **Triaging individual work items.** That's `/triage`'s job. If a specific item is blocking this skill's run, note it and move on.
## Output
A short, structured report back to the user:
```
## Engineering Optimizer — <date>
### Signals I pulled
- Git: <merge cadence, revision churn, flight cadence — 1–3 lines>
- Deploy: <candidate-a flights, Loki coverage — 1–3 lines>
- Work items: <deploy_verified leak rate, ## Validation compliance — 1–3 lines>
- Guide churn: <learnings scaled in last 2 weeks — 1 line>
### Matrix regrades (with evidence)
- <stage>: <old> → <new> because <signal>
- ...
### Next lever
<one proposal — title, scope, sketch of ## Validation — not a plan, one move>
### Scaled learnings (edits I made this session)
- <file>: <3-line summary of what the next agent now has that they didn't>
```
Then the hub finding is the durable artifact. The conversational report is ephemeral; the finding and the hub or shell corrections are what lift the fleet.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |