Skill · across everything, quietly

Project Compass

Your agent knows how to build things. This helps it work out what to build next — from what the project is becoming, not from general advice. Then, almost always, it builds what you asked for and says nothing.

Soumya Rauth · Creator & maintainer

npx skills add soumyaRauth/skills-hub --skill project-compass

One question

Given everything I know about this project,
what should this developer do next, and why?

Usually the answer is the thing you just asked for, and it builds it and says nothing. Occasionally it is not, and on those occasions the answer is worth more than the implementation would have been. You rarely know that this is the question you are asking — which is the point.

The problem

activity ≠ progress

Coding agents execute well. Ask for search, a refactor, another permission check, a dashboard — you get all of them, competently, one after another. That is the whole problem: execution never asks whether the sequence adds up.

Nine permission exceptions, each reasonable, are an authorization system nobody designed. Five performance changes with no measurement anywhere are five guesses with deployments attached. And the expensive one:

Add search.        Add export.          Add user groups.
Add filtering.     Add bulk delete.     Add permissions.
Add sorting.       Add saved filters.

Eight reasonable requests. Together they say we are building an administration system and nobody has defined the administration workflow — a sentence no single request could produce, and one the person making them cannot see, because they see one at a time.

Three modes, and the first one is the default

A build it · B build it, flag one thing · C pause and guide

Mode A is the overwhelming majority: no manufactured concerns, no “this looks fine from a project perspective”. Mode C is rare, is never a refusal, and always ends with the offer to build it as asked.

When it activates

No slash command needed. Installed, it is loaded when a request needs it and stays out of the way otherwise — and when it does shape the work, one ⚡ line says so. How the skills work together →

Engages	Direction questions — what next, should I add this, what am I missing — and requests that add another instance of a recurring pattern, lock in a data model or public contract, or contradict a recorded decision.
Stays quiet	Renames, copy, formatting, dependency bumps, test fixes — even in a drifting project — and declared exploration.
Depth	Passive by default: it reads and records, and says nothing. Sometimes one flag with the work; rarely a pause, which always ends with the offer to build it as asked. Never a gate.
Works with	Impact Map, Standards Compass, API Contract Guard

The moment it is built for

You:    Add another status to orders.

Agent:  I’d stop for a moment before adding this status.

        The problem isn’t really the new status. There’s no defined order
        lifecycle — pay.js treats paid as final, ship.js doesn’t check
        cancellation, and refund.js will refund a cancelled order. A fifth
        flag lands in a set of four that already contradict each other.

        What I’d do first: write down the states and which transitions are
        legal. Ten lines, half an hour. Then the new status goes into that
        instead of becoming a fifth exception.

        Say the word and I’ll just add the flag — you may know something
        the repository doesn’t.

Nothing was refused. The alternative is smaller than the work it replaces, it is startable today, and the evidence is three file names you can check in thirty seconds.

Every finding ends in an action

Not this	This
“There is no order lifecycle”	“Define the order lifecycle before adding a fifth status”
“There is technical debt”	“Extract the shared permission rule and route the three existing paths through it, before the fourth exception”
“The product direction is unclear”	“Decide what the dashboard is meant to help someone decide, before the next widget”

When several things could be done, they are ranked by what most improves the trajectory — blocking decisions, then broken core workflows, then domain-model problems, then boundaries getting expensive, then security and data integrity, and only then debt, performance and polish. Technical issues do not automatically outrank product and workflow ones.

The harder half: knowing when to shut up

An agent that comments on project direction four times a week gets uninstalled in week two, and the one real observation it would have made in week nine never arrives. So Modes B and C are gated, not judged.

Gate	Test
Recurrence	Three or more independent instances, each with a location you can name
Convergence	They share a cause, not a topic — could one decision have prevented all three?
Consequence	What breaks next, in terms of work already asked for. “This could get messy” fails
Actionability	A step smaller than the work it prevents. “Consider defining an authorization model” is not a step

Three out of four is a note in the project state, not a sentence to you. On top of that: one intervention per session, maximum — and a dismissed observation is closed permanently. Say “that’s intentional” and it is recorded as a decision with your reason, and never raised again, in any wording. Say “this is a throwaway prototype” and that becomes the frame every later recommendation is measured against, because you know the goal and it does not. Those rules are what make the skill survivable past month two.

What it remembers

.project-compass/
  project.md          what this is, who it serves — labeled, dated
  direction.md        what it is becoming, the biggest gap, the next step
  trajectory.md       dated entries: what changed, and which pattern it fed
  decisions.md        settled questions, including “we discussed this, proceed”
  open-questions.md   unresolved decisions affecting implementation
  blind-spots.md      gaps that cleared the bar, and what closes them

direction.md is “what should I do next?”, cached — so next week the answer costs one file read instead of a second reconstruction of the project. This is the difference between the skill and asking an agent “what am I missing?”: that question gets a fresh guess from nothing, every time.

The purpose of every file is better guidance later, not a record of what happened. Renames, formatting and dependency bumps are never written down; a trajectory that logs everything is a diary, and nobody finds a pattern in a diary. The repository always outranks the state, and recorded claims are re-verified before anything is built on them.

Everything is labeled

Label	Means
OBSERVED	Read directly — with the location
INFERRED	Concluded, with High or Low confidence, and what would overturn it
ASSUMED	Believed to make progress, unverified — and what breaks if it is wrong
UNKNOWN	Established as not known, and what would settle it

It will not invent your project’s purpose, users, market, deadlines, metrics, or history. When the objective is undocumented, “there is no documented objective” is the finding — usually a useful one — and recommendations say which parts of them that limits.

What it notices

What accumulated	What it has become	What to do about it
Search, filter, sort, saved views, bulk, export	A list-management workflow	One sentence naming who uses the screen and what they are finishing
Draft, submit, approve, reject, publish	A lifecycle	The states, the legal transitions, and who may cause each
Invite, role, permission, org, access, audit	An authorization model	Subjects, resources, actions — and does ownership outrank role
Payments, refunds, subscriptions, invoices	A billing lifecycle	How those four interact, before the fifth
Notification rules added per feature	An event system	The real events, their consumers, their guarantees
Timeout, retry, queue, cache, Redis	Five guesses	One number: what is slow, measured how, acceptable at what
UI passes while the workflow underneath breaks	A sequencing problem	Finish the path end to end, then return to the interface

Each detector requires specific evidence before it fires, and every one of them is a hypothesis until it has been checked against the code.

Answers it is willing to give

Keep going — this is the thing. (The most common non-silent answer.)
Settle one decision; three features are waiting on it.
Finish the workflow underneath before adding more interface on top of it.
Ship it and watch. Four passes on a working screen is guessing.
Measure it first. There is no performance problem here yet, only a suspicion.
Delete it. Nothing uses it and it is charging rent.
Write down the rule. It currently lives in four conditionals that disagree.

And, rarely and with the evidence attached: I can build this, but I don’t think it’s what the project needs right now — always ending with the offer to build it anyway, because you have context the repository does not.

Limitations

It sees the repository and the conversation. Your users, your market, what a stakeholder promised — invisible, and it says so rather than guessing
Value compounds with use. A first session can reconstruct a project model; a trajectory takes weeks to become one
Inherited history helps — on a repository that arrives with a pattern already in it, git history counts as evidence from the first session
Reading direction is judgment, not analysis. It will sometimes read focused work as a pattern; the four gates make that rare, and being overruled costs one sentence
It cannot tell you whether your idea is good. It can tell you that nothing in the repository connects it to anything else
Work done outside the agent is invisible unless it left a commit