Thank you for your interest in contributing to the Semantic Anchors catalog! This guide explains how to propose new semantic anchors and what makes a good semantic anchor.
- What are Semantic Anchors?
- Artifact Types: Anchor, Contract, Skill
- Quality Criteria
- Testing Your Semantic Anchor
- Viability Test (Does the anchor deliver?)
- Developer Setup
- How to Propose a New Anchor
- Anchor File Format
- Counter-Examples
- Categories
- Professional Roles
- PR Review Policy
- Issue Title Convention
- Code of Conduct
- Questions?
- License
Semantic anchors are well-defined terms, methodologies, and frameworks that serve as reference points when communicating with Large Language Models (LLMs). They act as shared vocabulary that triggers specific, contextually rich knowledge domains within an LLM’s training data.
Example: When you mention "TDD, London School" to an LLM, it activates knowledge about mock-heavy testing, outside-in development, and the work of Steve Freeman and Nat Pryce - much richer than simply saying "use mocks in testing."
The catalog ships three artifact types. Knowing which one you are proposing decides where your contribution belongs. The full rationale lives in ADR-007; the working definitions are here.
| Type | Function | Linguistic shape | Loading |
|---|---|---|---|
Anchor |
"What do I know?" — focuses pre-existing knowledge |
Noun / named concept ("Cockburn Use Cases") |
Passive (activation signal) |
Contract |
"What may I do?" — pins which anchors apply + invariants |
Declarative ("follows / NEVER / MUST") |
Always-on |
Skill |
"How do I do it?" — supplies procedure |
Verb / imperative ("Create / Verify / Write") |
On-demand |
-
Anchor — a named activation signal for a knowledge cluster that is already dense in an LLM’s training data. It focuses; it does not teach. Must pass the four Quality Criteria below.
-
Contract — terse, always-on shared vocabulary (in
CLAUDE.md/AGENTS.md) that pins which anchors apply and states invariants. The moment it describes how to do something step by step, that part belongs in a Skill. -
Skill — on-demand procedural machinery (
references/, prompts, a workflow) for a how the model cannot execute from a name alone.
Discrimination test:
-
Knowledge already dense in the LLM, only needs focusing → Anchor
-
Need to pin which anchors apply and what is allowed/forbidden → Contract
-
Need to describe how something is concretely done → Skill
The thin-prior rule. If a name is not dense in the training data, it is not an anchor — naming it does not reliably change the output structure compared to a generic prompt. What repairs it depends on what is missing: a missing meaning/framing → a Contract (it supplies its own meaning; a URL never repairs a prior); a missing procedure → a Skill. A thin name is never forced to be an anchor.
Before proposing a new semantic anchor, ensure it meets these four criteria:
Details
=== ✓ Precise The anchor references a specific, established body of knowledge with clear boundaries.
Good: "SOLID Principles" - five specific design principles (SRP, OCP, LSP, ISP, DIP)
Bad: "Good design" - vague and subjective
=== ✓ Rich The anchor activates multiple interconnected concepts, not just a single instruction.
Good: "Domain-Driven Design" - activates bounded contexts, ubiquitous language, aggregates, value objects, entities, repositories, etc.
Bad: "Use meaningful names" - single instruction with no conceptual depth
=== ✓ Consistent Different users invoking the anchor should get similar conceptual activation from the LLM.
Good: "Test-Driven Development" - widely documented methodology with consistent understanding
Bad: "Modern testing" - different interpretations by different people
=== ✓ Attributable The anchor can be traced to key proponents, publications, or documented standards.
Good: "Hexagonal Architecture" (Alistair Cockburn, 2005)
Bad: "Best practices" - no specific source or authority
|
Tip
|
Not sure if your proposal qualifies? Check our Rejected Proposals page to see previously evaluated terms that didn’t meet the criteria — and why. |
Before proposing, test the anchor with this prompt in an LLM:
What concepts do you associate with '<your semantic anchor name>'?|
Note
|
The proposal template includes a required LLM Activation Test Result field. Paste your test output there — it front-loads the Precise/Rich/Consistent signal for reviewers. |
Evaluate the response:
-
Recognition: Does the LLM recognize the term?
-
Accuracy: Is the explanation correct?
-
Depth: Does it cover multiple related concepts?
-
Specificity: Is the scope well-defined?
Recognition is not activation. A model can talk fluently about a term while naming it changes nothing in the output — or worse, silently substitutes an older concept or confabulates a plausible-but-fictitious one. The training-data-vs-practice article documents these failure modes across model families. The activation test above catches recognition; the viability test below catches delivery.
-
Before/After test. Give a model a task without the anchor term, then the same task with it. Does the output structure change? If not, the term is decorative, not functional.
-
Substitution check. Ask "What is [term]?" on a weaker model (Haiku-class). If it hedges, silently substitutes, or confabulates, the prior is too thin for an anchor — it belongs in a Contract (which supplies its own meaning), per the thin-prior rule in Artifact Types above.
-
Cross-model check. Does the before/after difference hold on at least one weak and one strong model? If it only fires on frontier models, note it as ★★ (needs qualification).
A term that passes the four Quality Criteria but fails the viability test is a Contract, not an Anchor.
This gate is topic-neutral. No subject area is privileged or banned — personality and assessment frameworks (MBTI, DISC, Big Five, HEXACO) are neither excluded for their topic nor admitted for being well-known. They must clear the same Viability Test as any other candidate, and — given their contested empirical standing — carry a == Criticism / == Current Status section. The rationale is in ADR-008.
-
Git
-
Python 3.12+ (for pre-commit hooks)
-
Node.js 20+ (for website development, optional)
Required for all contributors!
Run the installation script:
./pre-commit-install.shThis installs:
-
AsciiDoc Linter - validates anchor file syntax automatically
-
pre-commit framework - runs checks before each commit
-
Standard hooks - trailing whitespace, YAML/JSON validation
We use an automated workflow with GitHub Copilot to validate and enrich proposals:
Click the btn:[Propose New Anchor] button on the website or create an issue using our proposal template.
All you need to provide:
-
The term or concept name
-
An LLM activation test result (required)
-
(Optional) Why you think it would be valuable
GitHub Copilot automatically:
-
Tests the anchor against the four quality criteria
-
Either accepts or rejects the proposal
-
If rejected: Explains why it doesn’t meet criteria
-
If accepted: Enriches the issue with detailed information
Once accepted and enriched, Copilot is assigned to:
-
Create the AsciiDoc file in
docs/anchors/ -
Add all required metadata (categories, roles, proponents, tags)
-
Submit a Pull Request
-
Maintainers review and merge
Each anchor is stored as an AsciiDoc file with metadata attributes:
= TDD, London School
:categories: testing-quality
:roles: software-developer, qa-engineer, architect
:related: tdd-chicago-school, hexagonal-architecture
:proponents: Steve Freeman, Nat Pryce
:tags: testing, tdd, mocking, outside-in
[%collapsible]
====
*Full Name*: Test-Driven Development, London School
*Also known as*: Mockist TDD, Outside-In TDD
*Core Concepts*:
* Mock-heavy testing
* Outside-in development
* Interaction-based testing
*Key Proponents*: Steve Freeman, Nat Pryce ("Growing Object-Oriented Software, Guided by Tests")
*When to Use*:
* Complex systems with many collaborating objects
* When designing APIs and interfaces
* Distributed systems where integration is costly
====Required Metadata:
-
:categories:- One or more category IDs (see website for list) -
:roles:- One or more professional roles that use this anchor -
:proponents:- Key people, publications, or standards. If the anchor is an established term of art with no single originator (e.g.sota,ssot-principle), use the sentinelCommunityrather than omitting the required field or inventing an attribution. A missing proponent is a signal worth checking: a term traceable to no person, publication, or standard is weakly attributable and may be general vocabulary rather than a semantic anchor. -
:tags:- Keywords for search (optional but recommended) -
:related:- Related anchor IDs (optional) -
:advisory:- Short caution label (optional). Use only for counter-consensus framing: the anchor activates reliably but its framing conflicts with its own field’s documented consensus. Renders as a visible badge in the card/modal; keep the detail and the cited source in the== Criticism/== Current Statussection (single source of truth). Seeeisenhower-matrix.adoc.
Criticism and Current Status (research required, include when found):
The catalog is a lexicon, not a list of endorsements — inclusion means the term works as a precise pointer, not that we recommend the practice. For every new anchor, research whether documented criticism or drift exists, and add the finding as a section:
-
== Criticism— the method itself is contested. Only named, citable critique (critic + linked source), never vibes like "nobody uses this anymore". The section reports the discourse; it does not adjudicate. Where the discourse names alternatives, name them too. -
== Current Status— the method stands, but the training-data prior and the present have drifted apart: a newer edition exists (name the edition the prior likely points to), a successor emerged, or adoption faded.
Verify every linked source by actually fetching it before committing. If the research finds nothing citable, omit both sections — an empty section is noise. See #603 for the full-catalog triage behind this convention.
These are NOT semantic anchors:
| "TLDR" |
Underspecified instruction, no defined structure |
| "ELI5" |
Vague target level, no pedagogical framework |
| "Keep it short" |
Pure instruction, no conceptual depth |
| "Best practices" |
No specific body of knowledge, not attributable |
| "Modern approach" |
Too vague, not consistent across users |
Anchors are organized into 12 MECE (Mutually Exclusive, Collectively Exhaustive) categories:
-
Communication & Presentation
-
Design Principles & Patterns
-
Development Workflow
-
Dialogue & Interaction Patterns
-
Documentation Practices
-
Meta (repository and catalog concepts)
-
Problem-Solving Methodologies
-
Requirements Engineering
-
Software Architecture
-
Statistical Methods & Process Monitoring
-
Strategic Planning & Decision Making
-
Testing & Quality Practices
See the website for full category descriptions.
Anchors are tagged with professional roles to help filter relevant content:
-
Software Developer / Engineer
-
Software Architect
-
QA Engineer / Tester
-
DevOps Engineer
-
Product Owner / Product Manager
-
Business Analyst / Requirements Engineer
-
Technical Writer / Documentation Specialist
-
UX Designer / Researcher
-
Data Scientist / Statistician
-
Consultant / Coach
-
Team Lead / Engineering Manager
-
Educator / Trainer
For active periods with many contributions, maintainers apply a 20% sampling review:
-
At least 1 in 5 PRs receives a thorough, line-by-line review
-
All other PRs receive a high-level review (structure, quality criteria, CI status)
-
AI-generated PRs (GitHub Copilot) always receive human review
Every PR must pass all of the following before merge:
-
E2E Tests — all 28+ Playwright tests green
-
Lint & Format Check — ESLint + Prettier (no errors)
-
Dependency Audit —
npm audit --audit-level=highclean -
CodeQL — no high/critical security findings
-
AsciiDoc Linter — anchor files conform to format (pre-commit hook)
For new semantic anchors:
-
Quality criteria met (Precise, Rich, Consistent, Attributable)
-
All required metadata attributes present (
:categories:,:roles:,:proponents:) -
AsciiDoc format correct (
[%collapsible]block, proper attribute syntax) -
Anchor tested with LLM prompt (see Testing Your Semantic Anchor)
-
Documented criticism / edition drift researched — and captured in a Criticism or Current Status section with named, fetch-verified sources where found
For code changes:
-
No regressions in existing tests
-
No new high/critical security vulnerabilities
-
Follows ESLint/Prettier code style
All issues should follow a consistent [Type]: <Name> title format. This makes filtering, searching, and triaging materially easier.
| Prefix | Used For | Source |
|---|---|---|
|
New semantic anchor proposals |
Issue template |
|
New semantic contract proposals |
Issue template |
|
Improvements to existing anchors |
Issue template |
|
Bug reports |
Issue template |
|
Changes to project processes |
Issue template |
|
Feature requests |
Free-form |
|
Tracking issues for larger initiatives |
Free-form |
-
Use the issue template whenever one exists — the prefix is set automatically.
-
Free-form issues (no matching template) should manually use one of the recognized prefixes.
-
Apply going forward only — do not retro-rename closed issues.
-
EPICs use the bare
EPIC:prefix without brackets, as a sanctioned exception.
-
Be respectful and constructive in discussions
-
Propose anchors in good faith
-
Respect maintainer decisions on quality criteria
-
Focus on established, documented methodologies
-
Give credit to original proponents
-
Browse existing anchors on the website
-
Check the README for project overview
-
Open a GitHub issue for questions
By contributing, you agree that your contributions will be licensed under the same license as this project (see LICENSE file).
Ready to propose? Click here: Propose New Semantic Anchor