Contributing to Semantic Anchors

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?

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

Artifact Types: Anchor, Contract, Skill

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:

  1. Knowledge already dense in the LLM, only needs focusing → Anchor

  2. Need to pin which anchors apply and what is allowed/forbidden → Contract

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

Quality Criteria

We check every proposal against these four criteria. You don’t have to check them yourself before you propose a term:

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

Not sure if your proposal qualifies? Check our Rejected Proposals page to see previously evaluated terms that didn’t meet the criteria — and why.

How We Test a Proposal

We test every proposal ourselves with the Anchor Prior Test and post the result in the proposal issue. You don’t need to run any test before you submit.

The first step is an activation test. We ask a model:

What concepts do you associate with '<proposed term>'?

Then we 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?

Viability Test (Does the anchor deliver?)

We also run a viability test in our review. 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.

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

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

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

Developer Setup

Prerequisites

  • Git

  • Python 3.12+ (for pre-commit hooks)

  • Node.js 20+ (for website development, optional)

Installing Pre-Commit Hooks

Required for all contributors!

Run the installation script:

./pre-commit-install.sh

This installs:

  • AsciiDoc Linter - validates anchor file syntax automatically

  • pre-commit framework - runs checks before each commit

  • Standard hooks - trailing whitespace, YAML/JSON validation

Manual Hook Execution

Run all hooks on all files:

pre-commit run --all-files

Run specific hook:

pre-commit run asciidoc-linter --all-files
Local build artifacts (e.g. website/dist/, generated files in website/public/docs/) must not be committed. These are produced by the CI/CD pipeline.

How to Propose a New Anchor

We test proposals ourselves and use an automated workflow with GitHub Copilot to enrich accepted ones:

Step 1: Create an Issue

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 phrase

  • (Optional) A sentence or two on where or how you use it, or a link to a source

We run the tests ourselves and report back in the issue.

Step 2: Validation

  1. We run the Anchor Prior Test on the term and check it against the four quality criteria

  2. We accept or reject the proposal

  3. If rejected: we explain in the issue why the term doesn’t meet the criteria

  4. If accepted: GitHub Copilot enriches the issue with detailed information

Step 3: Copilot Creates the Anchor

Once accepted and enriched, Copilot is assigned to:

  1. Create the AsciiDoc file in docs/anchors/

  2. Add all required metadata (categories, roles, proponents, tags)

  3. Submit a Pull Request

  4. Maintainers review and merge

Step 4: Published

After merge, the new anchor appears on the website within minutes via automated deployment!

Anchor File Format

Each anchor is stored as an AsciiDoc file with metadata attributes:

= TDD, London School
:categories: testing-quality
:roles: software-developer, qa-engineer, software-architect
:related: tdd-chicago-school, hexagonal-architecture
:proponents: Steve Freeman, Nat Pryce
:tags: testing, tdd, mocking, outside-in
:tier: 2
:definition: TDD London School — also called mockist or outside-in TDD (Steve Freeman and Nat Pryce) — drives design from the outside in: start at the system boundary, mock collaborators to specify their interactions, and let the required interfaces emerge. It emphasises object roles and message-passing over verifying state.

[%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 sentinel Community rather 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)

  • :definition: - Two or three sentences that answer "What is X?" on their own, in one line: what the whole concept is and who it comes from, then its core mechanism and purpose. Use only facts the anchor file itself states; the German file carries its own translation. It is the answer block on the anchor page, the source of the meta description (shortened to 160 characters), the JSON-LD description and the definition field in anchors.json. Required: the unit tests fail for an anchor file without one

  • :tier: - Activation tier: 1 (frontier-only), 2 (needs qualification), 3 (broadly recognized). Internal: it is a judgement and is deliberately not rendered on the site

  • :prior-test: - Date the anchor was measured with the Anchor Prior Test. The key into the prior-test register; absent means "not measured", which is a statement about our records rather than about the term

  • :tested-on: - Every model the anchor was measured against, with its result, as model=yes|no pairs (e.g. haiku-4.5=no, sonnet-5=yes, opus-5=yes). Rendered in the modal. List all tested models, not only the successes: a model that was tried and showed no effect is a different statement from one that was never tried, and dropping it would read as the latter

  • :example-screenshot: - File name of an example image in website/public/examples/ (optional; e.g. swiss-style.webp). Shown with a caption below the anchor text in the modal and on the pre-rendered anchor page, not in llms.txt or the text exports. Use it for visual styles, where a picture of what a model produces from the name says more than a description. WebP, 720×900 px. The build fails if the file is missing. Read from the English file; the German file mirrors it

  • :example-page: - The starting page the example redesigns, which sets its section in the style gallery (optional): homepage (default) for visual styles, team-settings for design systems, which show their differences on an app page rather than a homepage. Any other value fails the gallery build

  • :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 Status section (single source of truth). See eisenhower-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.

Omitting the section does not mean discarding the result. Record the negative finding in the prior-test register with its date and the languages searched, so a later contributor can tell "researched, nothing found" from "never looked". A "nothing found" without its search frame is not evidence of absence — say what was searched and what could not be reached, and never report an unreachable source as a demonstrated absence.

Counter-Examples

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

Categories

Anchors are organized into 15 categories. Their scopes are MECE (Mutually Exclusive, Collectively Exhaustive); a single anchor may still belong to more than one category:

  1. Communication & Presentation

  2. Creative Writing & Storytelling

  3. Design Principles & Patterns

  4. Development Workflow

  5. Dialogue & Interaction Patterns

  6. Documentation Practices

  7. Knowledge Management

  8. Meta (repository and catalog concepts)

  9. Problem-Solving Methodologies

  10. Requirements Engineering

  11. Software Architecture

  12. Statistical Methods & Process Monitoring

  13. Strategic Planning & Decision Making

  14. Testing & Quality Practices

  15. UX & Visual Design

See the website for full category descriptions.

Professional Roles

Anchors are tagged with professional roles to help filter relevant content:

  1. Software Developer / Engineer

  2. Software Architect

  3. QA Engineer / Tester

  4. DevOps Engineer

  5. Product Owner / Product Manager

  6. Business Analyst / Requirements Engineer

  7. Technical Writer / Documentation Specialist

  8. UX Designer / Researcher

  9. Data Scientist / Statistician

  10. Consultant / Coach

  11. Team Lead / Engineering Manager

  12. Educator / Trainer

PR Review Policy

Review Requirements

All pull requests to main require at least one approving review before merging.

Sampling Review (~20%)

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

Automated Checks (Required to Pass)

Every PR must pass all of the following before merge:

  • E2E Tests — all 28+ Playwright tests green, including the axe accessibility scans (website/tests/e2e/accessibility.spec.js, WCAG 2.1 A/AA) of the catalog, the open modal, search/filter, dark mode, a doc page and the German variant. Lighthouse CI checks performance and SEO against the deployed site after merge to main.

  • Lint & Format Check — ESLint + Prettier (no errors)

  • Dependency Audit — npm audit --audit-level=high clean

  • CodeQL — no high/critical security findings

  • AsciiDoc Linter — anchor files conform to format (pre-commit hook)

What Reviewers Check

For new semantic anchors:

  1. Quality criteria met (Precise, Rich, Consistent, Attributable)

  2. All required metadata attributes present (:categories:, :roles:, :proponents:, :tier:, :definition: in EN and DE)

  3. AsciiDoc format correct ([%collapsible] block, proper attribute syntax)

  4. Anchor tested with LLM prompt (see How We Test a Proposal)

  5. Documented criticism / edition drift researched — and captured in a Criticism or Current Status section with named, fetch-verified sources where found

For code changes:

  1. No regressions in existing tests

  2. No new high/critical security vulnerabilities

  3. Follows ESLint/Prettier code style

  4. No build artifacts in commit (e.g. website/dist/, generated files)

AI-Assisted Reviews

This project uses CodeRabbit for automated AI code review on all PRs. CodeRabbit reviews are advisory — human maintainer approval is still required.

Issue Title Convention

All issues should follow a consistent [Type]: <Name> title format. This makes filtering, searching, and triaging materially easier.

Recognized Prefixes

Prefix Used For Source

[Anchor Proposal]:

New semantic anchor proposals

Issue template

[Contract Proposal]:

New semantic contract proposals

Issue template

[Improve]:

Improvements to existing anchors

Issue template

[Bug]:

Bug reports

Issue template

[Process Proposal]:

Changes to project processes

Issue template

[Feature]:

Feature requests

Free-form

EPIC:

Tracking issues for larger initiatives

Free-form

Guidelines

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

Code of Conduct

  • 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

Questions?

License

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