goal-finder — derive the goals a repo needs to finish

Understanding goal-finder

The goal-finder tool is designed to reconcile a repository's documented intentions with its current state to derive prioritized, verifiable goals. It's triggered by phrases like "what's left to finish" or "build a goal backlog". This is not a tool for loops or autopilot scenarios, but for establishing clear, actionable objectives.

Modes of Operation

goal-finder operates in two distinct modes:

• Mode A — Repo-wide backlog: This mode answers the question, "What does this whole repo/project need to finish?" It scans all documentation, clusters signals into coherent goals, prioritizes them, and produces a backlog with a build order. This is useful when you need a comprehensive view of a project's endpoint.

• Mode B — Contextual next-goal: This mode is for those in the midst of a task, asking, "What's the right goal to ask for next?" It scopes to the active task/files, identifies the highest-value, verifiable, session-sized goal, and hands it over as a ready /goal contract. By default, Mode B is used if it's clear the user is mid-task.

Goals as Contracts

Each goal derived by goal-finder is a contract with a verifiable completion condition. For example, a goal might state, "section X of the spec is implemented and <test> passes". If a check can't be articulated, it’s marked as "needs verifiable surface", and a proposal is made. This ensures every goal has a clear, objective endpoint, avoiding vague directives like "improve X".

Task and Goal Structure

A complete /goal is a single, self-contained paragraph that specifies:

1. Repo: The primary repository to work in.
2. Context: Embeds the relevant spec/section and constraints.
3. Task: The specific action to be taken.
4. Completion Condition: An objective verifiable surface, such as a passing test or a successful command exit.

These elements ensure that both the working model and any independent evaluator understand the task and expected outcomes.

Backlog and Phases

Goal backlogs are organized into phases, each with no unmet prerequisites, allowing for parallel execution. Concurrent goals that affect the same files are flagged for serialization or isolated checkouts. This structure ensures efficient workflow and resource allocation.

Compute Class and Task Allocation

Every task is assigned a compute: class, ranging from 1 (mechanical tasks) to 10 (tasks requiring significant judgment). This classification is crucial for task routing and efficiency, with each task labeled with a [TIER] and a why: line explaining the classification.

Documentation and Claims

A critical aspect of goal-finder is the distinction between documentation claims and code realities. An unchecked box or "not implemented" note may not reflect the current state of the code. Therefore, reconciling documentation against actual code is essential before asserting a goal's existence.

In summary, goal-finder provides a structured methodology for turning a repository's documentation and current state into actionable, prioritized goals, ensuring clarity and accountability in software development processes.