Evidence, structure, maintenance

Prickles is operational experience written for reuse: design rules, tooling expectations, review habits, and test discipline drawn from sustained delivery work, mainly while leading engineering teams. The canon is written so colleagues (current and former) can align on concrete expectations. Readers who do not report to this author may still reuse the patterns if they survive inspection in their own repositories.

Every tenet page carries traceable citations, worked examples where they earn their space, multilingual enforcement sketches, and dissent where credible counter-arguments belong. The intent is the same checkpoint for flesh-and-blood reviewers and for delegated drafting tools wherever the text can be made concrete. Supporting detail lives in plain sight inside each case file (origins, quotations, evidence, references, mechanical enforcement panels), not in a hidden appendix.

This page confines itself to process: what the corpus is, how it is sourced, how it is laid out on the site, how code samples pick languages, and how machine assistance was used to write the text. The editorial argument for publishing at all stays on Why Prickles.

The canon you see on Prickles is the publication: fifty-three numbered tenets grouped into nine pillars on the homepage, each opening into the same case-file scaffold described below. Editorial dates on major resets are echoed in site copy when a release materially rewrites the matrix; there is no separate handbook visitors must chase outside the URLs on this domain.

A tenet qualifies for inclusion when:

• grounded writing exists in authoritative practice (architecture guides, foundational papers, language references, tooling behaviour) plus modern commentary where the field keeps moving fast;
• there is practical evidence the organisation genuinely enforces limits (automated lint and duplication gates, behavioural tests reviewers trust, PR checklist language assistants are expected to honour, briefings surfaced inside coding-agent sessions, and sibling controls of the same shape);
• the claim can be articulated at three levels simultaneously: rationale for seasoned engineers, concrete guidance tuned for mixed human and agent readers, and the mechanical artefacts that prove the rule respects production constraints.

Before publication, reviewers walked overlapping candidates pillar by pillar: duplicates merged, names rewritten for plain English, rows retired when a stronger sibling already stated the obligation, and contradictions surfaced rather than softened. Whenever a shorthand rule looked fine in the abstract but weak once exercised against real repositories, the published case file picked up sharper examples or citations rather than leaving the headline unsupported.

Tenet URLs share a predictable case-file scaffold. Narrative chapters sit ahead of archival material so a reader scanning on mobile still receives the gist before dropping into quotations, long references, enforcement snippets, and footnotes.

The primary sequence is organised as follows.

• Summary. A plain-language unpacking of why the constraint exists inside modern software delivery workflows.
• Publishable excerpts. Where applicable, snippets sized for reviewer paste-back (for example checklist language or escalation triggers).
• Author stance. The italic verdict under Opinion; it is plainly marked commentary, not impartial reporting.
• Operational split. Human reviewers and delegated agents receive differentiated prose in one place rather than juggling separate cheat sheets keyed to the same identifier.
• Linkage. Related tenets are stated up front so reviewers can reconcile adjacent trade-offs quickly.

A labelled divider introduces the archival half: provenance narration, verbatim quotations pulled from primary sources, longer evidence excerpts, exercised examples with repository ties, enforcement panels keyed to specific languages where mechanical checks illustrate the posture, curated rule text for agents, articulated counter-arguments paired with rejoinders where material exists, and footnotes for micro-citations too noisy for the main prose.

Identifiers (F1, AI6, and so on) are stable across copy edits; breaking changes follow the versioning notes in repository documentation rather than silent URL swaps.

Every tenet case file ships a multi-language enforcement panel toward the tail of the sheet. Tabs are fixed to JavaScript, Python, TypeScript, PHP, Java in that order. The first, second, third, and fifth positions track languages with very high professional adoption in the surveys cited below. The fourth tab is not chosen that way: surveys would place C# ahead of PHP in this cohort, but the examples here are written from long professional experience in PHP and almost none in C#. Using C# would produce weaker, less trustworthy snippets, so PHP is the fourth language for that reason alone.

Adoption figures come from the Stack Overflow Developer Survey 2025 (professional developers: n reported as 24,759 of 49,095 total respondents). HTML/CSS and SQL lead headline usage tables but illustrate markup and querying, not general application code, so they stay out of implementation-level parity panels. The pull quote lists the five tab languages with their shares in that subgroup, including PHP's lower headline percentage, to make the editorial substitution above explicit.

Order-of-magnitude uptake was also checked against the GitHub Octoverse 2025 synthesis (including its note on TypeScript repository counts). Those sources support keeping JavaScript, TypeScript, Python, and Java in the set. They do not drive the fourth tab: that slot follows maintainer expertise, not ranking.

Tab order rationale. JavaScript opens on the widest survey share and common recognition. TypeScript follows for readers on modern web stacks. Python comes next as the largest syntactic shift away from ECMA-family syntax. PHP sits fourth for the author-experience reason stated above, not because it outranks other languages in the survey tables. Java closes the row as a widely taught JVM-family point of comparison.

Maintenance rule. The tab order freezes for twelve months absent a materially new survey cohort or a deliberate choice to change the fourth tab. Updates will restate sourcing years and regenerate pull-quote figures so readers can diff policy changes without rewriting underlying sample identifiers tied to anchored URLs.

Opinionated exposition lives on pillar pages and within clearly labelled headings on tenet sheets (Opinion blocks, argumentative pull quotes when present). Tone there may be direct because the goal is to force a decision in review. This URL is different: copy here is written in the same neutral register you would expect from an internal engineering handbook preface.

Promotional copy, founder narrative, and humour stay off this route deliberately. Guidance on voice for persuasive sections sits in repository documentation adjacent to branding notes; none of that material rewrites the methodological statements above.

Assistants based on large language models assisted with drafting and refactoring large portions of the manuscript (structural HTML, cross-link maintenance, tabular data, some explanatory prose). No model output ships without author review, consistent with the published collaboration tenet AI6 Self-Review Pass, which requires a critique pass before hand-off to human editing.

Tooling changes over the life of the project; therefore this page does not freeze model names, prompt hashes, or temperature settings. For auditability, rely on revision history: each merge record notes the human responsible for sign-off even when the diff contains machine-generated proposals.

Material changes to the matrix ship with redeployments of Prickles. Stable tenet codes (such as F1 or TA1) are kept constant on purpose so links from mail, chats, or reviews keep resolving after copy edits underneath.

A visitor-facing chronological change log does not yet exist here. For now, substantive updates appear as revisions to the published matrix and to individual case files. When a release rewrites the canon in bulk, that reset is signalled in editorial copy on the site rather than in a hidden file path.