agentleFS
harlan-zwharlan-zw/brundlefly/skills/slop-naming-recovery/SKILL.md

slop-naming-recovery

Skill7 starsChanged 35 days agoMITView on GitHub

Finds generic technical names that obscure user tasks and proposes names grounded in the product domain. Use when vague terms enter code, features, UI copy, or GLOSSARY.md, including implicit names and explicitly approved terms.

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. About 0 are common, 29 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈29

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Treat naming slop as a problem in the name, never a judgment about its author.

    line 11
  2. Distinctive:

    Read the target project's instructions, GLOSSARY.md, COPY.md, VISION.md, and naming decisions when available.

    line 16
  3. Distinctive:

    Look for term definitions in other project documents, such as CONTEXT.md, API docs, or decision records.

    line 17
  4. Distinctive:

    Follow its delivery and approval rules.

    line 19
  5. Distinctive:

    Do not create root documents automatically.

    line 20
  6. Distinctive:

    Default to an audit with proposed changes.

    line 26
  7. Distinctive:

    If naming approval is required, prepare the complete recommendation before asking.

    line 27
  8. Distinctive:

    When fixes and PRs are authorized, deliver supported changes within that scope.

    line 30
  9. Distinctive:

    Before selecting fixes in this mode, read frozen contracts and database approval.

    line 34
  10. Distinctive:

    Use the bundled clarity block for reader context, wording, order, and accessibility.

    line 38
  11. Distinctive:

    Add domain meaning, concept mapping, glossary decisions, and rename scope to that review.

    line 40
  12. Distinctive:

    Before collecting names, read the product context procedure.

    line 44
  13. Distinctive:

    Do not infer purpose from the glossary or architecture alone, or invent research, personas, purposes, or capabilities.

    line 46
  14. Distinctive:

    Before discovery, read the inspection procedure.

    line 52
  15. Distinctive:

    Read the naming checks and examples and the concept checklist.

    line 62
  16. Distinctive:

    Write one plain sentence: "[Person] uses [thing] to [task]." If the task is unclear, report the gap instead of inventing a name.

    line 63
  17. Distinctive:

    If the task is unclear, report the gap instead of inventing a name.

    line 64
  18. Distinctive:

    Prefer an established, accurate domain term from the project before introducing a new one.

    line 70
  19. Distinctive:

    Use concrete object names and task verbs that express user meaning or action.

    line 71
  20. Distinctive:

    Do not replace one vague label with another, such as changing every artifact to a resource.

    line 72
  21. Distinctive:

    Avoid cute metaphors, invented jargon, and names that imply unsupported capabilities or completed actions.

    line 73
  22. Distinctive:

    Prefer the smallest surface change that resolves the reading problem.

    line 80
  23. Very specific:

    Use a table: Current name | User task | Proposed name | Evidence | Impact /100 | Effort S/M/L | Confidence /100.

    line 87
  24. Distinctive:

    Use stable IDs across revisions so users can accept, keep, defer, or edit proposals independently.

    line 94
  25. Distinctive:

    Before applying an authorized rename, read the recovery procedure.

    line 99
  26. Distinctive:

    Use the saved-choice and measurement examples when a removal or verdict affects consumers.

    line 101
  27. Distinctive:

    Check saved selections and real report boundaries, including dates, missing inputs, denominators, and source identity.

    line 102
  28. Distinctive:

    Run the target's focused checks for affected behavior, imports, consumers, and links.

    line 104
  29. Distinctive:

    Search for displaced names and explain intentional remaining uses.

    line 106
  30. Distinctive:

    Check that each new name preserves meaning and lets its intended user predict the next action.

    line 108

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Slop naming recovery

Find implementation names that hide users' tasks. Recommend domain names with evidence before adopting them. The domain comprises users' objects, actions, and decisions: bookings, payroll, source symbols, and import paths. Treat naming slop as a problem in the name, never a judgment about its author. This Skill extends im-part-human's reader-focused editing with product naming review, and also works alone.

Scope and authority

Read the target project's instructions, GLOSSARY.md, COPY.md, VISION.md, and naming decisions when available. Look for term definitions in other project documents, such as CONTEXT.md, API docs, or decision records. Missing GLOSSARY.md does not make a documented name implicit or authorize a new glossary. Follow its delivery and approval rules. This Skill owns naming review, not publication or architectural redesign. Do not create root documents automatically.

Review documented and implicit names. Consistent canonical terms can still confuse users. An approved term remains authoritative during review. Propose a supported revision rather than silently overriding it. Record deliberate decisions and reasons. Reopen them only with relevant evidence or explicit user direction.

Default to an audit with proposed changes. Apply renames only within the user's authorized scope. If naming approval is required, prepare the complete recommendation before asking. Existing approval covers the agreed names and scope. Do not request it again.

When fixes and PRs are authorized, deliver supported changes within that scope.

Optional mode: avoid breaking changes

Before selecting fixes in this mode, read frozen contracts and database approval. For database changes outside this mode, read the same section before preparing a proposal. Freeze only requested boundaries. Defer blocked renames and complete independent fixes.

Use the bundled clarity block for reader context, wording, order, and accessibility. Reuse context supplied by im-part-human or another caller. Do not repeat an already completed clarity pass. Add domain meaning, concept mapping, glossary decisions, and rename scope to that review.

1. Understand the product and its language

Before collecting names, read the product context procedure. Establish users, problems, outcomes, actions, limits, and audience language from product evidence and representative code paths. Do not infer purpose from the glossary or architecture alone, or invent research, personas, purposes, or capabilities. Label language without customer evidence as inference. If purpose remains unclear, report missing evidence before recommending names. Base every proposal on this account. Word searches alone cannot establish a naming problem.

2. Find names and their users

Before discovery, read the inspection procedure. Inspect the full requested scope before ranking findings. Feedback limits do not limit discovery. For a repository audit, cover main journeys and user surfaces; keep feature requests focused. Trace representative inputs through producers to displayed results, including missing data and partial completion. Record the inspected revision, local changes, journeys, exclusions, and coverage gaps. Inspect ordinary domain names too. Generic technical words are search prompts, never a ban list. Preserve accurate audience vocabulary. Recommend an explanation first when it resolves the problem.

3. Recover the domain meaning

Read the naming checks and examples and the concept checklist. Write one plain sentence: "[Person] uses [thing] to [task]." If the task is unclear, report the gap instead of inventing a name. Map terms to definitions, code owners, user tasks, and public wording, including internal-only feature names. Separate concepts sharing a name; identify synonyms naming one concept. Preserve distinctions, relationships, and lifecycle states.

4. Propose and rank names

Prefer an established, accurate domain term from the project before introducing a new one. Use concrete object names and task verbs that express user meaning or action. Do not replace one vague label with another, such as changing every artifact to a resource. Avoid cute metaphors, invented jargon, and names that imply unsupported capabilities or completed actions. Preserve technical distinctions that affect user decisions. Plain language must remain precise.

Recommend one name per concept; offer an alternative only for an unresolved distinction. Show a before-and-after label or identifier, its evidence, and the names it would displace. Flag whether the name is implicit, glossary-approved, or required by an external contract. Separate UI wording, internal identifiers, and externally fixed names in the recommendation. Prefer the smallest surface change that resolves the reading problem. Public wording can improve without an API rename. Rank by user impact and confidence in the meaning, not occurrence counts or dislike of technical words. Show migration effort separately. Give highest priority to confusing names on important user actions.

5. Deliver or apply the recovery

Lead with the strongest supported finding. Use a table: Current name | User task | Proposed name | Evidence | Impact /100 | Effort S/M/L | Confidence /100. Link file lines or supplied sources. Explain scores briefly and identify missing evidence. Include affected surfaces and any required approvals or migrations beside each finding. Report justified technical names separately. If no supported problem exists, say so.

Turn actionable findings into numbered proposals using the feedback format. Show the exact proposed naming document change, its definition, displaced names, and map row when one exists. Use stable IDs across revisions so users can accept, keep, defer, or edit proposals independently. Group dependent proposals and explain why they need one decision. Interpret feedback per proposal. Silence and approval of one proposal do not approve the others. Revise affected definitions and examples before applying an edited name.

Before applying an authorized rename, read the recovery procedure.

Use the saved-choice and measurement examples when a removal or verdict affects consumers. Check saved selections and real report boundaries, including dates, missing inputs, denominators, and source identity.

Run the target's focused checks for affected behavior, imports, consumers, and links. In avoid-breaking-changes mode, verify the frozen contracts against the base revision and affected consumers. Search for displaced names and explain intentional remaining uses. Pass proposed wording and established context to the bundled clarity block; reuse its review of unchanged wording. Check that each new name preserves meaning and lets its intended user predict the next action. Report executed checks separately from source inspection and untested user understanding.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.