Skip to content

Adding items

New Mandatory items are the highest-leverage contribution to vibecodingisold. Every accepted item changes what every downstream user's planning tool will demand. The bar is correspondingly high: 9-field template fully populated, >=2 Tier-1 primary sources, mapped to one of the 7 LLM-failure-mode categories, propagated through every affected derivative file.

This page walks the workflow end-to-end.

Prerequisite — prove the gap

Before drafting an item, prove the gap exists in the canonical source:

  1. Search the relevant role file (core/roles/<role>.md) for keywords related to your proposed item. Use ripgrep, not eyeballs — items can have non-obvious names.
  2. Search the cross-reference graph (core/_cross-references.md) for related items.
  3. Search the anti-patterns file (core/anti-patterns.md) for related failure modes.
  4. Check if the gap is already named in a profile's V1-gaps section (e.g., mobile-app.md flags 5 gaps explicitly).

If the item already exists in some form, the contribution is a clarification or expansion, not a new item. That's still valuable but goes through the bug-fix workflow instead.

If the item genuinely doesn't exist, proceed.

Step 1 — Open an issue using the new-item template

Open an issue using .github/ISSUE_TEMPLATE/new_item_request.md. Fill in:

  • Proposed item title — Item NN — <verb-phrase>. Verb-first naming convention.
  • Role it belongs to — one of architect, backend, database, security, devops, sre, qa.
  • Why it's Mandatory (not Conditional) — what failure mode does omitting it cause in every project that activates this role?
  • Real-world failure citation — postmortem, incident report, public CVE. URL required.
  • Why AI tools systematically miss it — which of the 7 anti-pattern categories applies?
  • Sources you have lined up — at least 2 Tier-1 primary sources (URLs).

The issue gets a pre-discussion before you spend time on the full draft. The maintainer either confirms the gap is worth filling, or explains why it's better as a Conditional, or points at an existing item that covers the case.

Step 2 — Draft the item using the 9-field template

The canonical template is at .planning/worker-briefings/_shared/item-template.md. All 9 fields are mandatory, no exceptions.

### Item NN — <verb-first item name>

Category: Mandatory
Triggers when: always

1. What exactly:
[Concrete pattern, code snippet, or config — never a slogan. The reader must know precisely
what to implement, not just the topic.]

2. Why mandatory (failure mode):
[Specific failure that occurs when omitted, with a real-world citation. Include $ impact,
user impact, or production incident reference where available.]

3. Minimum implementation:
[~30-60 lines of compileable TypeScript+Node+Postgres code, or other stack if stack-specific.
Imports must be present. The snippet must compile.]

4. Failure modes of the minimum implementation:
[When does this minimum break? What's the trigger to upgrade?]

5. Validation method:
[Concrete test, tool, or command that verifies the item is wired up correctly.]

6. Why AI tools systematically miss this:
[Concrete reason. Map to one of the 7 categories in core/anti-patterns.md. Generic field-6
content is rejected — the LLM-failure-mode reasoning must be specific.]

7. Sources (>=2 Tier-1 primary):
- [Source 1: Title, URL, Tier]
- [Source 2: Title, URL, Tier]
- [Optional Source 3+: ...]

8. Cross-references:
- See also: <other-role>.md Item N
- Conflicts with: none / <item>
- Required for: <other-item>

9. Estimated time to retrofit (if added later instead of Day 1):
[Hours / Days / Weeks / "Rewrite required". Communicate urgency.]

<!-- ITEM-NN COMPLETE -->

The trailing <!-- ITEM-NN COMPLETE --> marker is used by the parser. Don't omit it.

Step 3 — Map field 6 to one of the 7 anti-pattern categories

The load-bearing field. From core/anti-patterns.md, the 7 categories cover:

  1. Underrepresentation in training data — RFC headers, distributed-systems patterns, security primitives that exist in standards docs but rarely in tutorial blog posts.
  2. Path-of-least-resistance bias — the proper implementation is more lines than the no-op alternative; LLMs default to the shorter path.
  3. Outdated patterns dominate the corpus — session-cookie auth in tutorials beats OAuth 2.1 PKCE in standards.
  4. Subjectivity assumed where it doesn't exist — "add structured logging" sounds optional; the model treats it as such.
  5. Plausible failure modes are absent from prompts — no one prompts "and make the regex catastrophic-backtrack-resistant"; the model generates without the limit.
  6. Cargo-cult composition — the model reproduces a popular framework's pattern even when the project's stack contradicts it.
  7. Confidence amplification on the wrong primitive — the model confidently uses a deprecated or insecure primitive because the corpus over-represents it (e.g., MD5 for password hashing in old code).

Field 6 must name the specific category and explain how it manifests for this item. Generic phrasing ("AI tools may miss this because they aren't always thorough") is rejected.

Step 4 — Cite >=2 Tier-1 primary sources

Tier classification is at Source Tier System. The canonical index is .planning/worker-briefings/_shared/source-tier-index.md.

For new items:

  • At least 2 sources must be Tier-1 (engineering org blog, standards body, named senior-engineer reference text, primary postmortem).
  • Tier-2 may supplement but cannot replace a Tier-1 source.
  • Tier-3 is forbidden (Stack Overflow, Medium personal posts, vendor marketing pages, Wikipedia, AI-generated content, anonymous sources, outdated docs).

If you don't have 2 Tier-1 sources lined up, the item likely isn't ready to be added. Either:

  • Find better sources first.
  • Add the item as a Conditional with a stricter trigger rather than as Mandatory.
  • Add the item as a Flag-and-Defer with the trigger condition that should re-open it for V2.

Step 5 — Set the cross-references

New items rarely live in isolation. Common cross-reference patterns:

  • Layered concern. The architectural commitment lives in architect.md; the implementation lives in the role-specific file. Cross-reference each direction.
  • Same pattern, different surface. Idempotency-Key on inbound APIs (backend.md Item 1) ↔ HMAC verification on inbound webhooks (security.md Item 29) — both are "verify this incoming thing has the property the contract requires."
  • Required-for chain. Item A is mandatory before Item B can be implemented (e.g., RLS context-set in repository pattern architect.md Item 4 is required for tenant isolation database.md Item 10).
  • Conflicts-with. Items that propose alternatives (rare; flag explicitly when present).

Update core/_cross-references.md to add the new item to the graph. The validator (validate-cross-references.py) catches stale or unresolvable references.

Step 6 — Propagate through the derivatives

A new item ripples through several files. Touch each in order:

  1. core/roles/<role>.md — add the item, update the role's item count in the file header, increment the role's item totals if you have a totals section.
  2. core/_cross-references.md — add the new item to the dependency graph.
  3. core/PLAN-REQUIREMENTS.template.md — re-generate or patch to include the new item under the role's section.
  4. core/profiles/*.md — for each profile where the item activates, add it to the Mandatory list with a one-line activation rationale. Update the mandatory_items_count in the profile's frontmatter. If the item is profile-specific (only fires for some profiles), document the activation logic.
  5. integrations/* files — re-generate or patch any tool-specific config files that aggregate the items (e.g., cursor/.cursor/rules/*.mdc, cline/.clinerules, aider/CONVENTIONS.md, prompt-templates/init-requirements-compact.md and prompt-templates/init-requirements-full.md).
  6. plugins/vibecodingisold/scripts/sync-core.ps1 or .sh — re-vendor plugins/vibecodingisold/core/ from the canonical core/. Do not edit plugins/vibecodingisold/core/* directly.

Step 7 — Run all validators

pip install jsonschema
python .github/scripts/validate-items.py
python .github/scripts/validate-numerical-contracts.py
python .github/scripts/validate-cross-references.py
python .github/scripts/validate-plugin-sync.py
bash .github/scripts/validate-plugin-fresh-install.sh   # POSIX
# or: .\.github\scripts\validate-plugin-fresh-install.ps1   # Windows

All five must pass before opening the PR. If any fail, fix locally first.

Step 8 — Open the PR

Use the PR template at .github/PULL_REQUEST_TEMPLATE.md. Specifically for new-item PRs, include:

  • Link to the prior approval issue from Step 1.
  • The 9-field item draft (the maintainer reviews the field-by-field quality, not just the diff).
  • The list of derivative files updated (Step 6 checklist).
  • The validator output (showing all 5 validators pass).
  • Source citations with tier classification.

Step 9 — Respond to review

The maintainer's review focuses on:

  • Field 1 (What exactly): is the pattern concrete and unambiguous?
  • Field 2 (Why mandatory): is the failure mode named with a real citation?
  • Field 3 (Minimum implementation): does the code actually compile? Are imports present?
  • Field 6 (Why AI tools miss this): is it specific to this item, mapped to a named category?
  • Field 7 (Sources): are >=2 Tier-1, properly classified, accessible?
  • Cross-references: are they bidirectional, accurate, complete?
  • Propagation: are all derivatives updated?

Expect 1-3 review rounds. The bar is high because the item lives forever in canonical knowledge; getting it right at submission saves more time than rushing the merge.

What if the item is V1.x scope, not V1.0?

After V1.0 launches (May 2026), vibecodingisold enters V1.x maintenance mode. New items go into batched V1.1 / V1.2 releases rather than continuous trickle-in.

For items that match a known V1 gap (e.g., a Mobile-Engineer-role item, an ML-Engineer item), open the issue and tag it v2-roadmap rather than expecting V1.x acceptance. V2 work has its own discussion thread (TBD post-launch).

For items that fit the existing 7 roles and don't expand scope, V1.x acceptance is appropriate.

What if I don't have time to do the propagation myself?

Then the contribution is incomplete and the maintainer has to do the propagation work. That's a friction the project can't absorb at scale.

The clean alternative: open the issue with the item draft (steps 1-3), and let the maintainer (or another contributor) do the implementation. This is welcomed for high-quality drafts even when the contributor can't complete the propagation.

The line is at the issue, not the PR. A well-drafted item idea in an issue is more valuable than a half-completed PR.

Where the re-brief pattern is documented

The Phase 3.5 re-brief pattern (used during V1.0 build to add gap-filling items) is documented at methodology/brain-worker-orchestration.md in the section on Phase 3.5 — Conflict resolution and adversarial gap-filling. Read it if you're proposing more than 3-4 items at once; the pattern keeps batched adds tractable.