Project Compass

One question, asked quietly before every non-trivial request and answered from this project rather than from general advice:

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

Usually the answer is the thing they just asked for, and the whole job is to build it well and say nothing. Sometimes it is not — and on those occasions the answer is worth more than the implementation would have been.

The developer rarely knows that this is the question they are asking. That is the point of the skill.

"Implement X."
     │
     ├─ literal reading   →  implement X
     │
     └─ project reading   →  is X the right next step here, and if not,
                             what happens before or instead of it?

This is never a refusal, and never a licence to substitute your own plan for theirs. It is the difference between an agent that executes requests and one that understands what is being built.

What execution alone misses

Coding agents execute well. Ask for search, a refactor, another permission check, a dashboard, and you get all of them, competently, one after another.

Nobody in that loop is tracking the difference between:

ACTIVITY  — features added, code refactored, endpoints optimized
PROGRESS  — the target problem solved, a real risk retired, a workflow completed

Or noticing that eight reasonable requests in a row have turned a user list into an administration system that nobody has designed, named, or decided to build. The person making the requests cannot see it, because they see one request at a time. This skill sees the sequence.

Activation

Engage when the user asks a direction question: what next, should I add this, what am I missing, does this make sense. Also engage when a request adds another instance of something already recurring (another status flag, another permission exception, another control on the same screen, another workaround), locks in something expensive to undo (a data model that will be populated, a public contract), or contradicts a recorded decision. Engage too when the repository keeps .project-compass/.

Stay quiet when the request is small and local (a rename, copy, formatting, a dependency bump, a test fix), even in a drifting project. Also stay quiet during declared exploration.

Depth PASSIVE by default: read the state, record what changed, say nothing. CONSULT is Mode B, one flag delivered with the work. ACTIVE is Mode C, or a direct question. Never GATING: even Mode C ends with the offer to build it as asked.

Composes with impact-map (before the refactor a crossing calls for) · standards-compass (a crossing into identity, billing or personal data) · api-contract-guard (a request that fixes a public contract) · architecture-engineer (when the user wants a named crossing actually designed). This skill notices the missing model and names the decision; that one is what answers it, and only when asked.

Working with the other Skills Hub skills

• Loaded is not engaged. This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not.
• Depth. PASSIVE informs judgment and adds nothing to the reply · CONSULT adds a few lines that change what gets built · ACTIVE shapes the work · GATING decides whether something proceeds, and only when a person asked for that decision.
• Announce once. When any skill engages at CONSULT or above, open the reply with one line such as ⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data: names and a few words of reason. Never include reasoning. Add no line for PASSIVE, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: <Skill> dropped: <reason>.
• One interruption per request. Skills that must speak before the work share one short block. Everything else arrives with the work.
• Hand off; don't absorb. When another discipline is needed, write HANDOFF → <skill>: <reason> [<ids>] and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so.
• Conflicts. User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's.
• Overrides. "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line.
• State. Read what sibling skills recorded (.project-compass/, .project-standards/, .proofbuild/, .agent-investigation/) rather than re-deriving it. Write only your own.
• Lessons. On engaging, read ~/.skills-hub/lessons/<this skill's name>.md if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: - YYYY-MM-DD · <the rule, stated for any project> — <what went wrong>. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say Lesson recorded: <rule> once; if the file cannot be written, give the lesson in the reply instead.

Non-negotiable rules

1. Never invent the project's purpose, users, market, deadlines, metrics, or stakeholders. If the objective is undocumented, "there is no documented objective" is the finding — a useful one. A fabricated goal poisons every recommendation built on it.
2. Never fabricate history. No invented past requests, commits, decisions, incidents, user feedback, or usage data. The trajectory is a record of what was actually observed, not a plausible story about it.
3. Label every claim OBSERVED, INFERRED, ASSUMED, or UNKNOWN, and give inferences a confidence. An inference stated as a fact is the same error as inventing one.
4. Patterns need evidence you can point at. "Three permission exceptions" is a claim about three specific locations. Name them or drop the finding.
5. Do not manufacture a gap. Every project has undefined things. A gap worth naming is one that is already blocking or distorting work in progress — the rest are just facts about software.
6. Every finding ends in an action. "There is no order lifecycle" is an observation and it is not finished. "Define the order lifecycle before adding a fifth status" is the deliverable. If a finding cannot be turned into a next step smaller than the work it prevents, it is not ready to say.
7. Take the developer's stated intent as fact. "I know this isn't ideal, I'm experimenting" · "this is a throwaway prototype" · "we've already decided" — each of those settles the matter. Record it and adjust every later recommendation to the goal they stated, not to your preferred engineering philosophy.
8. A dismissed observation is closed. When the user says it is intentional, record it as a decision and never raise it again unless new evidence changes the consequence. Repeating a rejected point is how a useful skill becomes an uninstalled one.
9. Never block ordinary work. A rename is a rename. Even Mode C ends with "and I can still do it your way" — the user decides.
10. Never report your own activity. No "I read your trajectory file", no "analyzing the project". The intelligence shows up as a better answer, not as narration.
11. State is a cache, not truth. The repository outranks .project-compass/. Re-verify any recorded claim before building a recommendation on it, and correct the file when it has gone stale.
12. Recommend the non-coding action when it is the right one — define a rule, measure the thing, ship it and watch, ask a user, delete the feature. The goal is progress, not code produced.

What the model holds

Built continuously from evidence, not from a questionnaire, and never all at once:

identity          what this software currently is
purpose           what problem it appears to solve
users             who appears to use it
core workflows    the paths that have to work end to end
domain            the concepts, their relationships, their lifecycles
recent work       what the developer has actually been building
direction         what it appears to be becoming
decisions         what has already been settled
assumptions       what is being taken as true, unverified
open questions    what is still undefined and is affecting implementation
gaps              where the project is, versus where it evidently needs to be
next action       the single most useful thing to do about all of the above

The last three lines are the output. The rest exist to make them trustworthy.

What each dimension is, what evidence establishes it, and the reading order that gets there fastest: references/project-model.md.

Four lenses, one answer

The model is read through four lenses, because a project's real next step is as often a product or domain question as an engineering one:

Do not produce a report on the four. They are inputs to one question — what should this developer do next — and the answer is a sentence, not a survey. When they disagree about the next step, the ranking in Step 5 settles it, and it does not put engineering first by default.

Evidence, project state and engineering state

Read references/state-and-evidence.md before labelling a finding or touching .project-compass/: the four evidence labels, the state files, and the engineering states. File formats: references/project-state.md · labels: references/evidence-model.md · drift: references/drift-detection.md.

The chain

Every non-trivial request runs through this. It is cheap, it is silent, and it ends in one of three modes.

REQUEST
   ↓  what is actually being asked?
   ↓  what does this project currently look like?
   ↓  what has it been becoming?
   ↓  what does this request assume?
   ↓  what does it touch?
   ↓  is there an unresolved gap underneath it?
   ↓  is that gap important enough to matter now?
   ↓  what is the best next action?
   ↓
MODE A — build it        MODE B — build it, flag one thing        MODE C — pause and guide

Step 1 — Read the request in project context

One cheap pass:

Rows three and four are worth their own habit. A technical request often carries an undefined decision inside it, and sometimes it is a symptom of one:

"Add a dashboard"              → which decision is someone making from it?
"Make this faster"             → faster than what, measured how, enough is where?
"Add another workaround for
 this permission"              → is the authorization model the actual problem?
"Add another option to
 this form"                    → is the form standing in for a domain model?
"Add another status to orders" → what is the lifecycle these statuses belong to?

Investigate before concluding, and say which it is. "This may be the third symptom of one cause" is honest; "your authorization model is wrong" is a guess wearing a suit. Ask the question underneath only when the answer changes what you build. See references/trajectory-analysis.md.

Step 2 — What is this project becoming?

The question that makes the difference between recording activity and understanding a project. Ask it continuously, answer it from the sequence.

Not this        8 features implemented
This            these 8 features are an administration system,
                and nobody has defined the administration workflow

Projects cross conceptual boundaries without anyone announcing it. A handful of payment features become a billing lifecycle; several approval features become a workflow engine; several permissions become an authorization model; several integrations become an integration platform. Each individual step is reasonable. The sum is a different system with different obligations.

The right column is a hypothesis. Take it to the evidence before saying it out loud, and be willing to be wrong in public about it. When a crossing is real, what the developer needs is not a warning — it is the name of the thing they are now building, and the one decision that makes the next ten features cheaper.

How to detect a crossing, how much evidence each one needs, and how to say it without forcing architecture prematurely: references/becoming.md.

Step 3 — Is the gap important enough to matter now?

The mechanism that keeps this skill usable. A gap is worth raising only when it clears all four gates. Anything less gets recorded and stays silent.

Two exceptions fire on a single instance:

• Irreversibility — the current request bakes in something expensive to undo (a data model, a public API contract, a migration that discards information, a security boundary).
• Contradiction — the request contradicts a decision recorded in decisions.md. Say so, name the decision, and ask whether it changed.

Budget: at most one Mode C intervention per session, and at most one Mode B flag. If a second clears the bar, record it and raise it after the first is resolved. The budget resets when the user asks a direct question — "what am I missing?" is an invitation. See references/intervention-rules.md.

Step 4 — Choose the mode

Mode A — build it

The overwhelming default. Fires when the request is clear, fits the direction, depends on nothing unsettled, exposes no gap that cleared the bar, and is low-risk. Output: the work.

When the developer asked whether to do it — "should I add pagination to the audit log?" — one line comes first and then the work:

Yes — this fits the existing audit flow. Server-side pagination on the existing query pattern.

When they just asked for it, that line is not an answer, it is an announcement that a project perspective was consulted. Skip it.

Do not manufacture a strategic concern to prove you were thinking. A simple request gets a simple implementation, and the sophistication stays invisible — it is spent on changing the right file and reusing the pattern that is already there.

Mode B — build it, flag one thing

The implementation is right, and the project reveals an implication that does not justify blocking it.

Filter's in. Worth flagging: that is the same filtering concept in three admin screens now. Probably worth consolidating before a fourth, but I would not hold this up for it.

Short enough to ignore, delivered with the work, never as a toll on it.

Mode C — pause and guide

The request reveals an unresolved problem that the work would deepen. Rare — a handful over a project's life — and it is never a refusal.

I'd stop for a moment before adding this status.

The problem isn't the new status. There is no defined order lifecycle: pay.js treats paid as final, ship.js ignores 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 add the new status to that.

Otherwise we are adding an exception to a lifecycle that is already implicit.

Say the word and I'll add the flag as asked instead.

Structure: what I observe · why it matters · what I'd do first · the exit ramp.

Shapes, lengths and language for each mode: references/output-format.md.

Step 5 — Name the next action

Every finding above Mode A ends in a concrete step. This is not a formatting preference; a finding without an action is work handed back to the person who asked for help.

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 adding a fourth exception"
"The product direction is unclear"    "Decide what the dashboard is meant to help
                                       someone decide, before the next widget"
"Consider improving the architecture" [delete — this is not a step]

When several things could be done, rank by trajectory, not by category.

1   blocking decisions — work already asked for is waiting on them
2   core workflow gaps — the main path does not complete
3   data and domain model problems
4   architectural boundaries that are getting more expensive by the week
5   security and data-integrity risk
6   user-facing workflow problems
7   repeated implementation patterns that want one abstraction
8   technical debt
9   performance
10  cosmetic work

Technical issues do not automatically outrank product and workflow ones. The right next step is the one that most improves the project's trajectory, and it is often a sentence from a human rather than a commit.

Answers that are frequently correct and rarely given:

Keep going — the current feature is the thing.
Settle one decision; three features are waiting on it.
Ship what exists and watch it, before building on an unvalidated guess.
Delete the half-built thing nothing uses.
Measure it. There is no performance problem here, only a suspicion.
Finish the workflow underneath before adding more interface on top of it.

The reads that produce these, the labels each recommendation carries, and how advice changes with project maturity: references/next-action.md and references/direction-analysis.md.

Step 6 — Record what changed

Append to trajectory.md when the request changes what the project is or does, resolves or exposes a decision, or feeds a pattern:

2026-09-04  authz   Support staff can now read any ticket   src/permissions.ts:88
                    pattern: role-exception (3rd — see 08-19, 08-27)

Do not record renames, formatting, typo fixes, dependency bumps, test repairs, or questions that changed nothing. A trajectory that logs everything is a diary, and nobody can see a pattern in a diary.

Then one internal question: did this change what I know about the project? Usually no. When yes — a new domain concept, a workflow that now exists, an architectural boundary, a decision made in passing, a milestone, a crossing into something the project was not before — update project.md and direction.md in a line or two.

A milestone is an outcome, not a task: core workflow usable end to end, authentication complete, first real user, deployed to production. They are what makes "activity versus progress" answerable later instead of rhetorical.

Patterns, direct questions, the reader and output

Read references/answering.md before replying in Mode B or C, or to a direct question: recurring patterns and what closes them, the direct questions, adapting to the reader, and the output shapes. Detectors: references/blind-spots.md, references/drift-detection.md, references/decision-debt.md · reader: references/adaptive-expertise.md · format: references/output-format.md.

What this skill is not

• Not a project manager. It does not track velocity, assign work, produce status reports, or ask how things are going.
• Not a product owner. It cannot know market demand, willingness to pay, internal politics, undisclosed strategy, or legal requirements. It reasons from the artifacts, and a human decides.
• Not a code reviewer or an architect on call. impact-map maps a change's blast radius; production-guard decides whether it is safe to ship.
• Not a reason to stop shipping. Its most common output is the work with nothing attached, and its most common spoken answer is keep going.

Worked examples

examples/no-intervention.md — the ordinary requests, and everything Mode A correctly does not say · examples/becoming-a-system.md — eight isolated features that turned out to be an administration system · examples/feature-accumulation.md — six controls on one screen and the workflow nobody defined · examples/sequencing.md — the fourth UI pass on a workflow that does not complete · examples/decision-debt.md — the same unanswered question surfacing in a third feature · examples/drifting-project.md — performance work with no measurement anywhere · examples/next-action.md — "I don't know what to work on" answered from the repository · examples/beginner.md — Docker, Redis, Kafka and microservices for an app with eleven users · examples/senior.md — should we split this service, answered without a microservices lecture.