Project Compass

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: dropped: .

• 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 → : [] 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/.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 · — . 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: 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.

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

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

1. Patterns need evidence you can point at. "Three permission exceptions" is

a claim about three specific locations. Name them or drop the finding.

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

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

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

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

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

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

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

1. 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 model

Every line carries one of four labels. Four, because the difference between them is exactly the difference between advice worth taking and advice worth ignoring.

| | Meaning | Must carry | | --- | --- | --- | | OBSERVED | Read directly — code, schema, config, docs, a commit, the user's own words | Where it was read | | INFERRED | Concluded from observations, with High or Low confidence | Which observations, and what would overturn it | | ASSUMED | Taken as true to make progress, unverified | What breaks if it is wrong | | UNKNOWN | Established as not known | What would settle it |

Users belong to exactly one organization    INFERRED (High)
    from: schema — users.organization_id is non-null with no join table;
          every query in src/repo/*.ts filters on it
    overturned by: any membership table, or a user seen in two orgs

Prefer evidence in this order: an explicit statement by the user · documentation and ADRs · the schema · the code · git history · configuration · the shape of the UI · inference from all of it. Never let inference overrule a stated fact, and never let a stale document overrule the schema. See references/evidence-model.md.

The project state

Persisted state is what separates this skill from asking an agent "what am I missing?" — that question gets a fresh guess every time, from nothing. This accumulates, and its purpose is better guidance later, not a record of what happened.

.project-compass/
├── project.md          what this is, who it serves, what it must do — labeled
├── 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 that are affecting implementation
└── blind-spots.md      gaps that cleared the bar, and what closes them

direction.md is the one that earns its keep fastest, because it is the file that answers what should I do next without re-deriving anything:

# Direction

**Appears to be**    A team task tracker with an increasingly capable list view
**Becoming**         A saved-query / list-management workflow          INFERRED (High)
**Key workflow**     create → assign → complete. Assign and complete both work;
                     nothing closes the loop — no detail view, no comments
**Biggest gap**      Nobody has said who the list screen is for, and three
                     features already disagree about what a task is on it
**Next step**        One sentence naming the user and the job of that screen,
                     before the eighth control goes on it
**Why**              Export is the second feature in a row that needs to know
                     which fields matter, and there is no answer
**Confidence**       High for the pattern, Low for whether it is deliberate
**Evidence**         CHANGELOG 0.5.0–0.9.0; TaskFilters.jsx:3 (4 fields),
                     SavedViews.jsx:4 (2), api/tasks.js:3 (3)
**Verified**         2026-09-10

Create only what carries state. A first session usually writes project.md and nothing else; direction.md appears when there is a direction worth recording, and blind-spots.md may never exist at all — that is a healthy project, not a failed run.

Read the directory before answering anything. It costs one pass and it is the entire point. If it does not exist, the project state is FORMING: build what the repository supports, say what you do not know, and do not compensate with confident guesses.

Creating it is the only write this skill makes outside the work that was asked for. Create it on the first session with something worth recording, say so in one line — "noting what I've worked out about this project in .project-compass/" — and never mention it again. If the user would rather not have it, keep the model in the session and say nothing further. Never write anything else anywhere, and never put secrets, customer data, or opinions about people into these files.

Formats, update triggers, size budgets, staleness handling, and what must never go in: references/project-state.md.

Engineering state

One of four, recorded in project.md, re-evaluated when the evidence moves.

| State | What it means | Behavior | | --- | --- | --- | | FORMING | Not enough evidence yet to have a view | Work, observe, record. Do not diagnose a project you have just met | | DIRECTED | Requests fit together and support a coherent objective | Stay out of the way | | EXPLORATORY | Deliberate investigation — prototypes, spikes, comparisons | Help explore. Gap detection is off for the area under exploration | | DRIFTING | Implementation is accumulating away from any coherent objective, on evidence | Guide, once, with the evidence |

EXPLORATORY is set by the user's own signals ("let's try", "prototype", "benchmark these", "throwaway") and by the artifacts of exploration. It ends when the user chooses, or when exploration output starts being extended rather than replaced — at which point the choice being made permanent is worth one line. See references/drift-detection.md.

---

The ch

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: soumyaRauth
• Source: soumyaRauth/skills-hub
• License: MIT
• Homepage: https://soumyarauth.github.io/skills-hub/

Install and usage instructions live in the source repository linked above.