Knowledge base

The working rules everything else follows from, and what each project is. Read these first if you read nothing else.

• Career and methodIndependence, not more evidence, catches false done claimsA working rule earned on Clarity, that the party producing evidence of correctness cannot be the party that grades it, so verification must come from a source the builder does not control.
• Career and methodKill a process the moment it stops shipping codeA four session, four role multi agent build workflow was measured, found to be producing coordination artifacts instead of software, and dismantled within a day.
• ClarityVerify against the system, not a documentA constraint written in a document is a hypothesis until it is tested against the machine, a rule that paid for itself when two recorded limits on the Clarity 2 build turned out to be false.
• Career and methodOrder fixes by blast radiusWhen a review turns up several defects at once, fix whatever breaks visibly first, the silent corruption second, and the performance change last, so a speed-up cannot cover the fixes underneath it.
• Wiki PipelineThe wiki pipelineAn agentic pipeline that harvests my project sources on a schedule and writes this wiki, so it stays current without me editing it by hand.
• ClarityClarity, a financial ledger for one dentist that answers what Excel cannotA web ledger built for a single practising dentist that speeds up his existing habit and answers who still owes him money, a question his spreadsheet cannot.
• Semantic SearchSemantic Search overviewA local-first hybrid search engine over PDF textbooks and a retrieval evaluation workbench, built as the bench the other two projects get measured on.

For anyone checking whether I understand evals and retrieval or only the vocabulary. Each page is a place I decided what the model is not allowed to do, and how that gets checked.

• ClarityDeterministic narration in Clarity InsightsClarity's Insights feature keeps a language model away from arithmetic entirely by having it narrate figures a typed engine already computed, gated by a deterministic faithfulness check.
• EaseMySemesterDeterministic prediction engineA rules based, LLM free ranking that predicts probable next year exam questions with a human readable reason for each.
• Wiki PipelineA checker with no toolsThe pipeline splits writing and checking into separate calls that share no tools or context, so the checker cannot go looking for agreement with the page it is grading.
• ClarityClarity's eval suite and the 86 to 100 investigationA nightly eval suite gates Clarity's narration on a hard faithfulness check, and a real investigation found the model was passing the letter of the rule while violating its intent.
• EaseMySemesterv2 topic ranking, backtested to frequency-onlyv2's topic ranking engine was built with five weighted signals, then backtested against a held-out exam year and shipped as frequency-only because the extra signals did not beat counting.
• ClarityDiagnostic "why" narration on Clarity's trend cardClarity's Insights trend card explains a revenue or margin move with an engine-computed cause, severity, and targeted link; the model only rewords a diagnosis it never gets to choose.
• Semantic SearchThe measurement loopSemantic Search built a repeatable, comparable, observable benchmark runner before tuning a single retrieval setting, deliberately scoring speed first and deferring answer quality.
• EaseMySemesterAnswer schema tracks staleness by constructionv2's answer table records the embedding config and prompt version an answer was built from, so a re-ingest or a prompt edit turns stale answers into a query result rather than an invisible drift.
• EaseMySemesterCitations as a child table, with Netter plates as see-alsoCitations moved from a JSONB blob to a foreign-keyed child table that cannot name a nonexistent book, and Netter plate references are additive, never a substitute for a grounded citation.

For founders and hiring PMs. Things I removed or declined to build, with the reason written down when I made the call.

• ClarityRetiring the time to entry metric as a headlineA published entry speed comparison was dropped as a headline after asking the actual user what he cared about, and rebuilt as an internal, non gating target.
• ClarityInsights drops the Payout Concentration sectionClarity removed the Payout Concentration section from Insights because payees are not yet linked in live data, so the section only ever showed an unassigned pile.
• ClarityRemove the duplicate Monthly tabClarity's Monthly tab was removed because Insights already surfaced the same and more granular figures, making Monthly a true duplicate.
• EaseMySemesterCitations name one page, even when the chunk spans severalRoughly half of v2's citations point at a chunk spanning more than one page, and the PM chose to leave citations single-page rather than cite a range.
• EaseMySemesterRanked topics view: topics ranked, questions listedv2's ranked-topics screen ranks subjects' topics by frequency and shows real sittings, but deliberately never ranks or scores individual questions because the bank cannot support it.
• ClarityFour borrowed skills, and only fourClarity 2's build took four published workflow skills and refused the rest, because the project's own loop already owns those jobs.
• EaseMySemesterQuestion screen drops exam marks, shows question type insteadThe mobile question screen's design called for a mark allocation the AKU past papers never printed, so v2 shows the question's type (long answer, short note, explain why) in that slot instead.

Redesigns that started with how students and a dentist I know actually used the thing, not with what I had planned.

• EaseMySemesterExam-first redesign and curated prepEaseMySemester was rebuilt from a question bank browser into a guided, exam-first prep tool that ranks review by what a student rated themselves weak on.
• EaseMySemesterTwo pane browse over a six level navigationReplaced a six level, five click navigation with a sidebar tree and chapter view after users showed the deep hierarchy was wrong for exam night.
• ClarityThe open case acceleratorTyping a patient's name surfaces their open treatment cases and autofills the treatment type, answering the receivables question the source spreadsheet could not.
• ClarityThe signed-in role picks the shell, not the width of the screenClarity 2 gives each of its two users a different shell chosen by the role in the signed-in cookie, and ships each shell as its own download.
• EaseMySemesterCram runs bounded by time, not by bank sizeCram runs were rebuilt from "the whole eligible bank" into a student-picked 10/25/45 minute run sized from the corpus's real word counts.
• EaseMySemesterCram swipe: got it or flag to revisitCram's advance gesture was given a direction, right for got it and left to flag for revisit, and the completion screen now offers to re-run just the flagged cards.
• ClarityHistory tab redesigned to rows, chiplets, and a real pagerClarity's History tab moved from one card per transaction to a single table with patient chiplets and a First/Last, numbered-page pager backed by a real total.
• EaseMySemesterKeyword search over the question bankv2 shipped Postgres full-text search over question and answer bodies, scoped to enrolled subjects and ranked by recurrence rather than text score, with every result snippet drawn from the field that actually matched.
• EaseMySemesterBank browse: subject to chapter to question listv2's subject to chapter to question list navigation was already built by the styling pass, verified against production data, with a chapter-count line-wrap defect fixed.
• ClarityThe clinic's four-page website, built for reviewA phone-first, four-page replacement for the clinic's website, built and verified behind a noindex preview address while the launch waits.

Every feature above rests on data someone could get wrong. These are the checks that compare it against its source instead of against a number someone remembered.

• EaseMySemesterThe content contractA strict, deterministic markdown format and parser that makes ten years of hand curated exam questions machine verifiable before any analytics feature can trust them.
• EaseMySemesterThe question bank is checked against the papers, not a remembered numberv2's reconciliation script re-derives the expected question bank shape from the source corpus itself on every run, rather than trusting a number someone wrote down once.
• Wiki PipelineThe weekly drift auditOnce a week the pipeline rereads one group of pages in full against their sources, rotating through the groups, to catch facts that drifted after they were written.
• EaseMySemesterStore the printed page on ingest, not derive it from an offsetv2's corpus ingest reversed a decision to compute a chunk's printed page from one stored offset per book, after three separate books proved the offset was not constant, and now stores the printed page itself.
• EaseMySemesterImport integrity: edited questions and malformed tagsTwo import bugs fixed in the same week, a silently stranded edited question and an undercounted truncated appearance tag, both closed by making the importer refuse rather than guess.
• EaseMySemesterOne definition of a paper, used everywherev2 standardised on counting distinct papers, not distinct sittings, for every band and count derived from question recurrence.
• EaseMySemesterCoverage weighted by topic recurrence, declined questions excludedv2's per-subject coverage bar weights a read question by its topic's paper count rather than counting questions flat, and drops the 82 declined questions from both sides of the fraction.
• EaseMySemesterOne Postgres store instead of Neon plus a SQLite VMv2 design drops v1's split data layer, questions in Neon and the textbook corpus in a SQLite file on a VM, for one Neon Postgres database with pgvector.
• Wiki PipelineSources are written oldest firstThe pipeline writes its sources in a fixed order, the old knowledge base first and the newer, higher priority sources after it, so a newer source corrects the baseline rather than the reverse.

What is kept out of public view, who is allowed in, and how the privacy claims are tested against what is actually stored.

• Wiki PipelineExport by allowlist, not by tier aloneThe site's /wiki export dropped from 75 published pages to 58 after an allowlist of folders was added on top of the tier check, since some Tier A claims should not have had a public URL at all.
• ClarityThe front desk is refused money twice, at the gate and in the appClarity 2 refuses the attendant the money addresses with a 403 from the gate before any app bytes are served, and again inside the app.
• Wiki PipelineGrade a numbers page row by row in the exportThe /wiki export grades a numbers page row by row, holding back any table row graded below its page's tier and then dropping the tier column before it writes the page.
• EaseMySemesterPrivacy notice and terms, tested against the schemav2's privacy notice and terms replaced one-paragraph stubs and are tested against the real schema, so a claim about what data is held cannot drift from what the database actually stores.
• EaseMySemesterThe past-paper corpus stays outside the repositoryv2's source corpus is read from a local directory named by an environment variable, never committed, because it is Al-Karim University material and the repository is meant to be public.
• Wiki PipelineSource harvesting and redactionA per-project source list defines exactly which files and GitHub repos the pipeline reads, with redaction applied before anything is written, and job search notes kept separate from project fact.
• ClarityOne Pages Function gates the whole Clarity 2 project, not Cloudflare AccessClarity 2's design-review login is a custom middleware function reading encrypted host settings, chosen over Cloudflare Access, HTTP Basic auth, and a repository-held credentials file.
• ClarityClarity 2's design review is reachable at the clinic's own address, behind a loginClarity 2's whole Pages project, including the clinic's own subdomain, now sits behind a fail-closed login that tells the app which of two people signed in, so the design review happens at the real address.
• ClarityThe made-up clinic behind Clarity 2's design reviewOne seeded, deterministic clinic of ten invented patients that both shells show on the same day, follows the clinic's own calendar, and can be reset.
• EaseMySemester · SupersededGoogle OAuth only for the mobile PWAv2 shipped hand-rolled Google OAuth with an invite list, email plus role deciding access, a revoked account's sign-in refused before a session is minted, and citations verified across eight books; auth was later replaced by email and password.

For technical readers. Scheduling, recovering from a stopped run, fixing concurrency in the right order, and putting a ceiling on what a run can spend.

• Wiki PipelineTreating a usage limit as an expected stateAfter one run hit a usage limit and discarded an hour of finished work, the pipeline was rewritten to commit as it goes and resume a stopped batch without redoing anything.
• Semantic SearchSequencing the concurrency fixes by blast radius, not discovery orderFive concurrency defects found in a deep review were fixed in an order chosen by dependency and failure severity, not by the order they were found.
• EaseMySemesterShared LLM client with retry, fallback, and a run budgetv2's ingest, eval, and generation scripts share one LLM client library with retry, a one-time fallback model, a cumulative cost ceiling, and timeouts, provable against a fake transport with no network.
• Wiki PipelineThe nightly schedulerThe pipeline runs hourly under Windows Task Scheduler, skips silently when there is nothing to do, harvests once a day, re-exports the site's figures after any productive run, and self-schedules a resume run when a usage limit stops it early.
• Wiki PipelineA read-only desktop app with one writable cellA portable Windows app reads the whole pipeline state and the vault, and can write exactly one thing, an application's status, because that is the only fact no agent can observe on its own.
• Wiki PipelineWiki pipeline numbersThe batching caps and thinking budget that keep each pipeline run cheap, and what happened when thinking ran uncapped.

Timelines, numbers with their caveats, and the questions still open. Reference rather than argument.

• Wiki Pipeline · OpenWiki open questionsThe checker proves a page matches its source, not that the source is still true, and the pipeline has no answer yet for a fact that quietly stops being current.
• EaseMySemesterEaseMySemester numbers, v2v2-specific defensible numbers for EaseMySemester, with their caveats.
• EaseMySemesterEaseMySemester timelineDated milestones for EaseMySemester, newest first.
• EaseMySemesterEaseMySemester timeline, early v2 (continued)Earlier dated milestones for early EaseMySemester v2, continued from timeline-v2-early, newest first.
• EaseMySemesterEaseMySemester timeline, v1 and earlierDated milestones for EaseMySemester from origin through v1, newest first.
• EaseMySemesterv2 design system, tokens and specimenv2 built a token-based design system, palette drawn from the corpus's own atlas material rather than a brand, with a drift-detecting tokens page, then applied it across every screen.
• EaseMySemestershadcn/ui migration with an animated dark mode switchEaseMySemester's admin and student UI was rebuilt on shadcn/ui with a semantic color token system and a self-built animated light/dark switch.
• ClarityDesign review work order 2, the two shells and a made-up clinicClarity 2's second design-review work order, a role-correct desk and phone shell over a seeded, resettable made-up clinic, built and verified at the real address.
• ClarityDesign review work order 3, the desk's Today entry pathClarity 2's third design-review work order gives the desk's Today its write path, one entry row, a money line that moves, and a just-saved entry corrected in place.
• EaseMySemesterEaseMySemester: all project pagesFull index of EaseMySemester feature, decision, and reference pages, split out of the project overview.