Elevate

Elevate

Produce one focused improvement plan: 5 specific, well-grounded improvements per dimension across the seven lenses. The output is a plan, not implementation. Each item names a specific file, function, or flow; states what to do, why it matters, effort, and impact; and the whole report ends with one recommended first move.

When to use

Use this skill for whole-product audits where the goal is a prioritized, multi-axis improvement plan — not a single-aspect review. Output is calibrated to the project's platform (web, macOS, iOS, or a mix detected from the repo).

Do not use for:

• Single-file code review or refactor — use a dedicated single-file review skill.
• Security-only audits — use a dedicated security-review skill.
• Build-time optimization only — use a dedicated build-optimization skill.
• Presentation deck review — use a dedicated deck-review skill.

Core workflow

> Example invocation. User: "elevate this repo." → Detect platform (read manifests) → survey entry points, key features, and recent commits → gather 7-10 candidates per dimension → verify each (drop ~40% that fail grounding checks) → rank the top 5 per dimension → synthesize the report, ending in one First move. Result: a 35-item, file-grounded plan printed inline (saved only if asked). Full output shape: examples/sample-report.md.

1. Detect the platform. Read the project root for package.json, *.xcodeproj, Package.swift, Info.plist, framework configs, and lockfiles. Classify as web, macOS, iOS, or mixed and record the reasoning. Detection cues: references/dimensions.md (Platform cues section). If the user has already named a peer the product should feel like ("Linear", "Things 3", "Raycast"), record it as the Attractiveness anchor.

1. Survey the codebase. Read entry points, top-level configs, key feature directories, dependency manifests, and recent commit history. Open enough files to ground later recommendations in real names and paths — not generic advice. Aim for breadth here, not depth in any single file. If the codebase is too large to survey end-to-end in one pass, prioritize entry points + most-recently-modified files + manifests, and explicitly flag the unscanned areas in the report's Coverage line.

1. Identify candidates. Walk the seven dimensions in order. For each, gather 7-10 candidate improvements grounded in observed code (more than the final 5 you'll ship, because verification will drop some). Use the per-dimension lenses in references/dimensions.md. Do not curate yet — verify first, rank after.

1. Verify every candidate. For each candidate, run the three grounding checks below (Quote, Anti-existence, Citation-resolves). Drop any item that fails. Keep a brief log: candidate title, the grep / quote check you ran, the verdict. The dropped items go into a required Dropped during verification section of the final report (see references/output-format.md) so the work is visible to the reader.

This is the most important step — calibration on real codebases showed ~40% of un-verified findings are wrong (either the proposed fix is already in place, the cited code does something different than claimed, or the file/line is mislocated). Doing the verify pass inside this skill means the user does NOT need to run a separate validation workflow afterward.

1. Rank and select. From the survivors, pick the top 5 per dimension by leverage (impact ÷ effort, with a lean toward items that unblock others). If fewer than 5 survived verification, state the count and reason in that dimension's section — never pad to hit 5.

1. Deduplicate and synthesize. A single issue often touches multiple dimensions (e.g., a fragile auth flow is both Stability and Security). Assign each issue to its primary lens once. Then produce the final report per references/output-format.md, ending with one recommended first move — the single highest-leverage item to ship first, picked from the 35.

End-to-end shape: examples/sample-report.md.

Grounding requirements per finding

Every item that enters the report must clear five checks. A finding that fails any of them is hallucinated, not real — drop it rather than patching the proof later.

1. Quoted proof. Open the cited file. Quote 1-5 lines from the exact location that demonstrate the issue. The quote goes into the report's Proof: field (see references/output-format.md). If you can't quote it, you haven't read it — drop the item.

1. Anti-existence check — with verbatim grep output. Before claiming a fix is missing, grep the cited file and obvious siblings for the proposed fix. Record BOTH the literal command you ran AND its complete stdout (or # (no matches) for empty results). Paraphrased results like "grep found only line 119" are FORBIDDEN — they hide real matches and were the dominant failure mode in calibration. If the actual stdout shows the guard, method, flag, or pattern you'd add already exists, the finding is "already done" — drop it.

Examples of what to grep:

• Proposing a deadline → grep for deadline:, withTimeout, Timer, DispatchSourceTimer in the file
• Proposing a guard → grep for guard, precondition, and the variable name
• Proposing an actor → grep for actor, nonisolated, MainActor on the target type
• Proposing a cache → grep for the cache name pattern and its invalidation sites
• Proposing accessibility additions → grep for accessibilityLabel, accessibilityRotor, accessibilityHint, accessibilityElement, accessibilityValue, accessibilityHint in the same view file
• Proposing config → grep for the value as a literal AND for UserDefaults / @AppStorage / config-struct fields that may already expose it
• Proposing test coverage → grep for the symbol-under-test across Tests/

1. Citation resolves. file:line must point to code that actually contains the claim. If you cite Foo.swift:42 and line 42 is a comment about a different topic — or the file doesn't exist — the finding is mislocated. Re-find or drop.

1. Falsifier zone in the proof. When the claim is "X is missing from Y" (most common shape), the proof quote must span enough context that if X were present it would visibly appear in the quote. For a SwiftUI view, that means the quote must include the closing } of the body / view-builder block — otherwise a chained modifier like .accessibilityLabel(...) two lines below your cited range stays invisible and you'll falsely flag an "already done" item as missing. For an actor or class method, the quote must include the closing } of the method. The rule: the proof must contain the place where the proposed fix would be, not just adjacent code.

1. Re-read immediately before writing. Right before adding a verified item to the report, do one final Read of the cited file at the cited line range and confirm the proof text still matches and the falsifier zone is still clear. This is a free sanity check that catches stale-cache reads and any drift between candidate-gathering and writeup. Items added without this final re-read have been the source of the residual ~14% false-positive rate in calibration.

These checks compound: a finding that "looks plausible" but fails check 2 (because the grep stdout actually shows the fix exists) or check 4 (because the falsifier line was just outside the quoted range) is the most common error mode. Most missing-feature claims about a polished codebase are "already done" — invest in the grep AND the wide-enough quote before the writeup.

Dimensions

| Lens | One-line definition | |---|---| | Performance | Speed, smoothness, resource cost — does it feel fast under realistic load? | | Functionality | Feature completeness — does it do what users came to do? | | Stability | Doesn't crash or break under normal conditions (no force-unwraps, error boundaries, sane defaults). | | Reliability | Behaves correctly under adverse conditions (retries, offline, idempotency, recovery, data integrity). | | Security | Attack surface, secrets handling, auth/authz, dependency CVEs, platform security posture. | | Usability | Easy and pleasant to operate — accessibility, navigation, discoverability, error recovery, native conventions. | | Attractiveness / Sexiness | Visual polish, motion, materials, micro-interactions, app icon, onboarding delight — does it feel premium? |

The Stability/Reliability split is deliberate — keep them distinct so the report doesn't double-count the same issue. If an issue fits both, prefer Reliability when the trigger is environmental (network, offline, concurrency, hardware) and Stability when the trigger is internal (logic bugs, force-unwraps, missing error boundaries). Detail in references/dimensions.md.

Output contract

• Target 5 items per dimension. If verification drops a dimension under 5, state the count and reason in that dimension's section — do NOT pad to hit 5.
• Each item must cite at least one specific file, function, flow, or component (e.g., src/auth/SignIn.tsx:42, Sources/AuthClient/AuthClient.swift, "the onboarding flow"). No generic advice.
• Each item is tagged effort: S | M | L and impact: S | M | L — see references/output-format.md.
• Each item includes: title, location, Proof (a quoted 1-5 line excerpt from the cited file, wide enough to include the falsifier zone per Grounding rule 4), Verified (the literal grep / search command and its verbatim stdout, per Grounding rule 2), what to do (specific), why it matters, effort, impact.
• Required section: First move — one item picked from the surviving set, with a one-paragraph justification of why it ships first.
• Required section: Dropped during verification — one line per candidate that failed grounding checks (drop reason: "already in place", "mislocated", "cited code does something else", etc.). If you genuinely had zero drops, say so explicitly; an empty section is more credible than a missing one.
• Optional section: Deferred — real items considered but cut from the top set, one line each with the reason.

Full report shape, tagging conventions, and length guidance: references/output-format.md.

Non-negotiable constraints

• This skill produces a plan, not code changes. It is error-proofed via allowed-tools (frontmatter): Edit and NotebookEdit are withheld, so it cannot modify existing project files even by mistake — only Write is available, and solely for the optional saved report (see Output destination). If the user explicitly asks for follow-up implementation, that is a separate task outside this skill's tool grant.
• Recommendations must be grounded in observed code AND must pass the three grounding checks above (Quote, Anti-existence, Citation-resolves). If a dimension has fewer than 5 findings that survive verification, state the count and reason explicitly. Speculative items are permitted ONLY when you have a specific code anchor that resembles the pattern (e.g., "this view file has no accessibilityRotor even though sibling views do — verifying the absence is enough"). Pure inference about what might be wrong without grepping for it is forbidden and counts as padding.
• The seven dimensions are fixed. Do not add, remove, merge, or rename them — even if the codebase makes one feel thin.
• The First move must be one specific item, not a category or a vague directive.
• Do not iterate, refine, or self-critique past one pass. Produce the report once.

Stopping conditions

• One survey pass, one analysis pass, one synthesis pass. Do not loop.
• If the platform cannot be confidently classified after reading the manifests, ask the user once before proceeding.
• If the user supplied an Attractiveness anchor that conflicts with the detected platform (e.g., "feel like Things 3" for a web app), note the mismatch in the report and adapt the anchor's principles rather than copying surface details.

Before responding, confirm:

Structural checks (about the report as a whole):

• Exactly 7 dimension sections, in the canonical order (Performance, Functionality, Stability, Reliability, Security, Usability, Attractiveness/Sexiness).
• Up to 5 items in each dimension. If verification dropped some, state the count and reason in the dimension's section instead of padding.
• A Dropped during verification section exists. If no candidates were rejected, say so explicitly — a missing section reads as "didn't actually verify."
• A First move section exists, names one specific item by title, and includes a one-paragraph justification.
• No issue appears under two dimensions — duplicates have been resolved to a single primary lens (using the Stability/Reliability tie-breaker rule when both apply).
• Speculative gap-fillers (if any) are explicitly tagged speculative, not silently padded with generic advice.

Per-item checks (about every item that survived to the report):

• The Output contract above is satisfied — every required field present (title, location, Proof, Verified, Do, Why, Effort, Impact tags), no paraphrased Proof or Verified.
• All five grounding gates passed (Quote, Anti-existence with verbatim stdout, Citation-resolves, Falsifier zone in Proof, Re-read immediately before write).
• Effort and Impact tags are not all M/M across the report — recalibrate if so.

If any check fails, fix the report before responding. Do not ship a partial or off-contract plan.

Output destination

Print the full report inline. If the user asks to save it, write to elevate-plan-{YYYYMMDD}.md in the project root unless they specify another path. Do not silently create files.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: welshofer
• Source: welshofer/elevate
• License: MIT

Install and usage instructions live in the source repository linked above.