Project Compass

---
name: project-compass
description: "Use when asked what to build next, whether to add something, or what is being missed; when a request adds another instance of a recurring pattern (another status, permission exception, option or workaround); when it locks in a data model or public contract; or when the repository keeps .project-compass/. Works out what the project is becoming, notices systems nobody defined and undecided business rules, and turns that into one next step. Mostly silent: build it is the default. Not for renames, copy, formatting, dependency bumps, or questions unrelated to direction."
---

# 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.

<!-- skills-hub:protocol -->
### 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.
<!-- /skills-hub:protocol -->

## 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:

| | Reads for |
| --- | --- |
| **Product** | What each feature is for · who asked · whether the workflow completes · complexity nobody needed · value nobody has stated |
| **Business** | The rules the code encodes · operational burden being created · what a customer already depends on · what breaks a process rather than a test |
| **Domain** | Entities, relationships, lifecycles, invariants, ownership, and the vocabulary the team actually uses |
| **Engineering** | Architecture, coupling, duplication, boundaries, data model, APIs, tests, performance, reliability, security |

**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:

| | |
| --- | --- |
| **What is being asked?** | The literal request |
| **What is it evidence of?** | Which project concept it touches — authorization, billing lifecycle, notification semantics, admin workflow, performance |
| **Is there a question underneath it?** | *"Should we use Redis?"* is rarely about Redis |
| **What is the developer trying to accomplish?** | The request is a means. Name the end, and check whether the request actually reaches it |
| **Does it depend on something unsettled?** | Check `open-questions.md` and `decisions.md` |
| **Does it feed a pattern already recorded?** | Check `trajectory.md` and `direction.md` |

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.

| What accumulated | What it has become |
| --- | --- |
| Search · filter · sort · bulk action · export · saved views | A list/query management workflow |
| Draft · submit · approve · reject · return · publish | A lifecycle, i.e. a state machine |
| Invite · role · permission · organization · access · audit | An authorization and tenancy model |
| Payments · refunds · subscriptions · invoices · dunning | A billing lifecycle |
| Several notification rules, added per feature | An event-driven communication system |
| Several reporting screens | An analytics product, with its own data questions |

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.

| Gate | Test |
| --- | --- |
| **Recurrence** | At least **three** independent instances, each with a location. Existing code and git history count — a project can arrive with the pattern already in it |
| **Convergence** | They share a *cause*, not a topic. Three permission exceptions in three unrelated features converge; three commits to one file do not |
| **Consequence** | You can name what goes wrong next, in terms of work that already exists or is already asked for. "It could get messy" fails this gate |
| **Actionability** | There is a specific next step smaller than the work it prevents — four named questions to answer, not "think about architecture" |

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.