agentleFS
sssemilsssemil/SKILLS/skills/brutal/brutal-wayfinder/SKILL.md

brutal-wayfinder

Skill2 starsChanged 4 months agoMITView on GitHub

Map and resolve planning work whose route is still hidden by research, prototypes, access, or decisions spanning multiple sessions. Use for large or foggy efforts that cannot yet produce a decision-complete Brutal specification and implementation tickets.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read ../brutal-shared/integration-resolver.md, resolve the work store, and load its support module.

    line 14
  2. Distinctive:

    Read repository instructions, domain context, ADRs, and existing map state.

    line 17
  3. Very specific:

    Use type:investigation for every map and investigation ticket.

    line 18
  4. Very specific:

    Use Source: brutal-wayfinder.

    line 23
  5. Very specific:

    Use brutal-grill to name and confirm the destination.

    line 51
  6. Very specific:

    If no fog remains and the decisions fit the current planning conversation, return to brutal-plan without creating a map.

    line 56
  7. Distinctive:

    Create the map first, then child tickets, then native relationships where supported.

    line 61
  8. Distinctive:

    Ask whether this run should resolve one frontier question or continue through ready agent-only questions.

    line 73
  9. Very specific:

    Add newly visible questions, graduate sharpened fog into tickets, and move newly excluded work to Out Of Scope.

    line 79
  10. Distinctive:

    Use adapter assignment, states, comments, parents, and blockers.

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

Brutal Wayfinder

Persist a resumable map of questions until the route to a decision-complete specification is clear. Produce planning decisions, not destination implementation.

Required Context

  1. Read ../brutal-shared/integration-resolver.md, resolve the work store, and load its support module.
  2. Read ../brutal-grill/SKILL.md.
  3. Read repository instructions, domain context, ADRs, and existing map state.
  4. Use type:investigation for every map and investigation ticket. These artifacts never enter the implementation task queue.

Map Contract

Use Source: brutal-wayfinder. A map contains:

## Destination
## Notes
## Decisions So Far
## Not Yet Specified
## Out Of Scope

The destination states what must exist when wayfinding ends. Decisions So Far is an index of resolved ticket names and one-line outcomes, not a duplicate of their full resolutions. Not Yet Specified holds in-scope fog that cannot yet be phrased as a precise question.

Each child ticket contains its parent, one precise Question, blockers, claim, status, and one mode:

  • research — agent-only primary-source investigation
  • prototype — human-in-the-loop artifact for behavior or design feedback
  • grilling — human-in-the-loop decision using brutal-grill
  • task — prerequisite work needed to expose facts for a later decision

A prerequisite task must unblock a planning decision; destination implementation belongs in the later Brutal plan.

Chart A Map

  1. Use brutal-grill to name and confirm the destination.
  2. Map breadth-first: group questions that must be researched or decided together into one coherent investigation scope. Create separate tickets only for different blockers, modes, owners, or independently useful decisions; record the remaining fog without prematurely slicing it.
  3. If no fog remains and the decisions fit the current planning conversation, return to brutal-plan without creating a map.
  4. Present the destination and a one-line list of initial scopes, blockers, and fog. Publish only after explicit approval; show full ticket bodies only when requested.
  5. Create the map first, then child tickets, then native relationships where supported. Mirror parent and blocker references in every ticket body.

Persist the map and children through the resolved work-store contract. Use the local adapter's investigation paths or remote parent/child artifacts, logical queue states, and prepare-before-create strategy. Never create local work-store artifacts for a remote adapter.

Work A Map

  1. Load the map as the low-resolution index and query open children.
  2. Identify the frontier: open, unblocked, unclaimed tickets.
  3. Ask whether this run should resolve one frontier question or continue through ready agent-only questions.
  4. Claim a ticket before work. In continuous mode, pause before any human-in-the-loop ticket.
  5. Record the full resolution on the ticket, mark it done, and append its linked one-line outcome to Decisions So Far.
  6. Add newly visible questions, graduate sharpened fog into tickets, and move newly excluded work to Out Of Scope.

Use adapter assignment, states, comments, parents, and blockers; preserve the same information in bodies when the provider has no native representation.

Complete the map only when no open ticket or fog remains. Mark the parent done and hand its reference to brutal-plan, which consumes the decisions, proposes any domain-document changes, and links the map from the final specification.

On rerun, deduplicate by Source, parent reference, and exact ticket title. Report partial publication or update failures precisely so the next run can resume rather than duplicate artifacts.

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.