Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (51 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

73 lines (51 loc) · 4.23 KB
Raw

Contributing to elevate

Thanks for considering a contribution. elevate is intentionally small and bounded — its value comes from the strict 7-dimension contract and the 5-item-per-dimension cap. Most useful contributions add depth to what's already there rather than reshape the core.

What's likely to be accepted

  • Additional sample reports in examples/ — new platforms (server-side codebases, React Native, Electron, Tauri, etc.), new product categories, or different anchor styles.
  • New platform cues in references/dimensions.md — e.g., entries for Flutter, Kotlin Multiplatform, server-side languages.
  • Sharper dimension lenses in references/dimensions.md — concrete signals the skill should look for that aren't already named.
  • Fixes to typos, broken links, factual errors in references or examples.
  • Documentation improvements — clearer phrasing, better installation steps for clients I haven't tested.

What's unlikely to be accepted

  • Adding, removing, merging, or renaming the seven dimensions. The report contract depends on them. The Stability/Reliability split in particular is deliberate; the tie-breaker rule keeps them distinct.
  • Changing the 5-item-per-dimension cap. Padding to 6 dilutes the prioritization signal; cutting to 4 means at least one dimension was under-explored. 5 is the contract.
  • Removing the "First move" requirement. That single recommended item is the most valuable line of the report.
  • Adding iteration / self-critique loops. elevate is one pass by design. Iterative refinement skills are a different category.
  • Adding code-execution scripts. This skill produces a plan, not actions. Implementation belongs in separate, focused skills.

If you want one of the above, please open a discussion before opening a PR — there may be a more constructive path (e.g., a sibling skill that composes with elevate).

How to test a change

elevate is a Claude skill — it has no runtime test suite. Test changes by:

  1. Symlinking your fork into your local Claude Code skills directory: 
    ln -s "$(pwd)" ~/.claude/skills/elevate-dev
  2. Editing the skill description so it doesn't collide with the published version (e.g., change the name to elevate-dev).
  3. Running it against at least two different codebases (one web, one native if possible).
  4. Verifying the "Before responding, confirm" checklist at the end of SKILL.md still all holds.
  5. Reading the output as if you'd never seen the skill before — does each item still stand on its own?

A change that improves output on your test codebase but breaks the verification checklist for another platform is a regression.

Style and tone

  • Imperative voice in the skill body and references. "Detect the platform" not "the platform should be detected."
  • Plain prose in user-facing text. No emojis in skill output. No marketing language in the report itself.
  • Be specific. "Improve performance" is a regression; "Decode entry images off the main actor in EntryRow.swift:38" is the standard.
  • No padding. If a section is short, that's fine. The skill explicitly prefers honesty over volume.

Commit message convention

Conventional Commits format:

  • feat: add Flutter platform cues to dimensions.md
  • fix: correct broken link in README
  • docs: clarify Attractiveness anchor wording in SKILL.md
  • example: add Tauri sample report

Keep the description in the imperative; under 72 characters for the subject line.

Reporting issues

Issues are welcome for:

  • Bug reports — elevate produced output that violated its own contract (e.g., 4 or 6 items in a dimension, generic advice without file grounding, missing First move section).
  • Platform-detection misses — your stack wasn't correctly classified.
  • Documentation gaps — something in the README or references is unclear or wrong.

For bug reports, include:

  • The platform (Claude Code, Desktop, claude.ai, API).
  • The codebase shape (language, framework, approximate size).
  • What you asked Claude.
  • What elevate produced (or refused to produce).
  • What you expected instead.

License

By contributing, you agree that your contributions will be licensed under the MIT License, the same license as the rest of the project.