erudeon/ops — Project Rules
Read this file first. When a rule here conflicts with anything else, this file wins.
What this is
This repository is how erudeon runs itself: the company handbook, the SOP and runbook library, go-to-market, people and hiring, finance policy, and the business backlog.
erudeon builds two products.
Pass The Year is exam preparation for Dutch university students (Erasmus Rotterdam,
UvA, Maastricht).
Flow is its social and events companion.
Their code and their technical documentation live in erudeon/passtheyear.
Claude is the primary author and reader of this repository. Non-technical collaborators reach most of it through issues rather than files, which is why the routing table below matters more than any other section: most requests are a filing question before they are a writing question.
This repository contains no code.
The four things that never go in here
Breaking one of these is not a style mistake, it is an incident.
-
No named students, customers, or personal data of any kind. GitHub has no retention policy, keeps edit history permanently, and sits outside the PII map in
passtheyear/docs/COMPLIANCE.md. erudeon is a data controller, so a student's name in an issue is a processing record nobody agreed to. Customer conversations belong in the Hub CRM's own follow-up tasks. This extends toproduct/research/, which holds synthesis only and never a raw interview. When a document needs to refer to a person, refer to the role. -
No accounting. Invoices, VAT returns, contractor payments and the books live in Jortt.
finance/here holds policy and decisions only: what we are willing to spend, who approves it, and how contractors are paid. A number that belongs in a ledger does not belong in a markdown file. -
No technical documentation.
erudeon/passtheyearis the single source of truth for every technical rule. Several SOPs here deliberately overlap with documents that already exist there. Those SOPs are thin: who performs it, when it is triggered, what approval is needed, and a link. They never restate the procedure. Two implementations of one rule is a bug, and this is the likeliest place in the company to introduce one. -
No code, with three named exceptions. Executable files live under
.github/— the workflows and the small scripts they call — underskills/, which carries the templates and helper scripts a skill needs to produce a marketing artefact, and undersite/, which renders this repository as a website and reads it without ever writing to it. None does product work: a.github/script keeps this repository honest about itself (opening an issue when a document goes stale, for instance), askills/asset is only ever an input to something a person is making, andsite/only ever displays what is already here. Product code stays inerudeon/passtheyear, and so does every technical rule — a skill here says go and read it there rather than keeping a copy, because a copy is the two-implementations bug rule 3 exists to prevent.skills/README.mdandsite/README.mdeach record their own decision and its cost. A fourth exception is a bug.
Where things go
Most requests are a filing question. Answer it with this table before writing anything.
| What you have | Where it goes |
|---|---|
| A repeatable process involving people | operations/sops/ — SOP format |
| Something we do when a thing breaks | operations/runbooks/ — runbook format |
| A thing that broke, after the fact | operations/incidents/ — postmortem format |
| "We chose X over Y, and here is why" | company/decisions/ — ADR format |
| How we do something, explained | a handbook page under people/, company/ or go-to-market/ |
| A fact to look up later | operations/vendors/, people/onboarding/access-matrix.md, operations/obligations.md |
| A task somebody needs to do | an issue, not a file |
| Thinking out loud, notes, a half-formed idea | a discussion, not a file |
| A campaign being planned or run | go-to-market/campaigns/YYYY-MM-slug/ |
| A finished HTML deliverable we send to people outside | go-to-market/documents/ — the site publishes it at /share/<name>/, see that README |
| A repeatable way of MAKING an artefact (a demo, a deck) | skills/ — a skill, not prose |
| A student's name, an invoice, a deploy command | none of the above — see the four rules |
When two rows could fit, prefer the one that is read under pressure. A runbook that is really an SOP wastes a minute; an SOP that is really a runbook wastes an outage.
Document standards
Every document opens with this line, directly under the title:
It is not decorative.
Review: is what the documentation sweep reads to open a review issue when a document
goes stale, and Classification: is what makes rule 1 visible on the page instead of
buried in a spec.
Default to internal.
Use confidential for commercial terms, anything legal, and anything about pay.
Shapes. Four document types, four shapes, all of them in templates/.
Use the template, do not improvise one.
- SOP — Purpose, Scope, RACI matrix, process flow, steps as Who / When / How / Output, exceptions table, metrics, related documents. The exceptions table is the most valuable part and is never omitted.
- Runbook — Purpose, prerequisites checklist, numbered steps each carrying the exact command plus expected result and if it fails, verification checklist, troubleshooting table, rollback, escalation, run history. "Run the script" is not a step.
- Decision record — DACI header (Driver, Approver, Contributors, Informed), then
Context, Options considered, Decision, Consequences.
Numbered
NNNN-slug.md, never renumbered, never deleted. A superseded record is marked superseded and kept. The options not taken are most of the value. - Postmortem — blameless, written about the system and never about a person. Every SEV1 and SEV2 gets one within a week.
Why the shapes differ (Diátaxis): a runbook is a how-to followed under pressure, a handbook page is an explanation read once to understand, and a vendor list is reference looked up and never read through. A document that mixes two of these serves neither.
Writing rules.
- One sentence per line, wrapped near eighty columns (semantic line breaks). Prose reflowed as one long line produces a diff where changing a word rewrites the paragraph, which makes documentation changes unreviewable.
- Filenames are lowercase kebab-case
.md. Dates areYYYY-MM-DD. Campaign folders areYYYY-MM-slug. - Every directory carries a
README.mdindex. When you add a document, add it to that index in the same commit. - Write for somebody who joined last week. Spell out the acronym the first time.
- No em dashes in anything a member or customer will read. Internal documents may use them.
Which skill writes which document
Reach for the tool rather than improvising the shape.
| Destination | Skill |
|---|---|
operations/sops/ |
/process-doc |
operations/runbooks/ |
/runbook |
operations/vendors/ |
/vendor-review |
company/risk-register.md |
/risk-assessment |
company/reviews/ |
/quarterly-review, /status-report |
| an existing process that is not working | /process-optimization |
| a contract to read before signing | /review-contract |
The operations plugin skills need no connector and work today.
Most small-business plugin skills require QuickBooks or HubSpot; erudeon uses Jortt and
its own Hub CRM, so those commands do not apply here.
What is borrowed from that plugin is its cadence, which lives in
company/operating-rhythm.md.
Working in this repository
Commit straight to main.
This is deliberate and it differs from erudeon/passtheyear, where every change goes
through a pull request.
Requiring a review round-trip for a typo fix is how handbooks die.
Do not apply the other repository's branching rules here.
Commit messages name the document and what changed about it:
sop: add the contractor offboarding access checklist.
Open a pull request only when the change is large enough that somebody should see it before it lands, or when it changes a rule in this file.
Issues carry the work. Every issue carries four things, and a workflow enforces it rather than trusting anybody to remember:
| Field | Values |
|---|---|
| Type | Task, Bug, Feature — organisation-level, shared with passtheyear |
| Area | area:marketing, area:ops, area:people |
| Priority | P0 blocking now, P1 this week, P2 this month, P3 agreed but unscheduled |
| Assignee | Always somebody. An unassigned issue is nobody's |
The priorities are deliberately relative to now rather than to a moment in the
academic year, so they still mean something in March.
Do not recreate the focus: taxonomy here.
An issue missing any of the four gets labelled needs-triage with a comment saying
which field is missing.
Discussions carry meeting notes, ideas, and decisions still in progress. A discussion that reaches a conclusion becomes either a decision record or an issue.
Deferred, so do not build it
Partnerships and association outreach. When it arrives the rule is already settled: the work is an issue here ("sign three associations this term"), and the people and conversations are rows in the Hub CRM. This repository never becomes a second contact store.
Related
erudeon/passtheyear— the code, anddocs/for every technical rulepasstheyear/docs/OPERATIONS.md— hosting, deploys, backups, monitoringpasstheyear/docs/COMPLIANCE.md— the PII map, consent, retention, erasurepasstheyear/docs/BRANCHING.md— branches, releases, versioning