Cursor dual-wiki operating model

Why the wiki comes before implementation

The current product spans marketing claims, documentation, role-specific workflows, privacy semantics, multi-tenant authorization, survey logic, analytics, and personal development. Without a canonical knowledge structure, the public site, application copy, API behavior, and admin controls will drift.

The dual-wiki model creates two synchronized representations of every material capability:

1. External Experience Wiki — what customers and users may be told, what they can do, and how to use it.
2. Internal System Wiki — how the capability works, who can access it, what data it uses, what invariants apply, and how it is operated.

A third shared index links the two.

Recommended repository structure

AGENTS.md
.cursor/
  rules/
    000-capablio-product-constitution.mdc
    010-dual-wiki-change-contract.mdc
    020-layout-and-design-system.mdc
    030-accessibility-responsive-and-i18n.mdc
    040-multitenancy-security-and-privacy.mdc
    050-content-and-marketing-truth.mdc
    060-testing-observability-and-release.mdc
    070-feedback-data-visualization.mdc
wiki/
  README.md
  shared/
    feature-index.md
    traceability-matrix.md
    glossary.md
    role-permission-matrix.md
    route-map.md
    decision-log.md
  external/
    README.md
    product/
    solutions/
    pricing/
    security/
    help/
    api/
    release-notes/
    _templates/
  internal/
    README.md
    product/
    architecture/
    data/
    security/
    operations/
    analytics/
    integrations/
    adr/
    runbooks/
    _templates/

Keep .cursor/rules flat unless the installed Cursor version is explicitly verified to handle nested project rules reliably.

Stable feature identifiers

Every material capability receives a stable ID used in both wikis, requirements, code comments where useful, analytics events, tests, and release notes.

Recommended format:

CAP-<DOMAIN>-<NNN>

Examples:

• CAP-AUTH-001 — Verified tenant invitation
• CAP-AFF-004 — Per-question exposure cooldown
• CAP-AFF-006 — Coverage feasibility simulation
• CAP-360-003 — Rater nomination and approval
• CAP-PDP-002 — Force-next-once PDP recurrence override
• CAP-ADM-010 — Org-scoped HR designation
• CAP-OPS-008 — Audited support access

Do not encode database IDs, current route names, or vendor names into stable feature IDs.

External wiki page contract

Every external capability page should answer:

• Who is this for?
• What problem does it solve?
• What can the user do?
• What can the user not do?
• What information is visible to whom?
• Which plan includes it?
• What are the main steps?
• What are the important limitations and prerequisites?
• Where can the user learn more or get help?

Suggested frontmatter:

---
feature_id: CAP-AFF-004
title: Question cooldowns
status: draft
public: true
audiences: [tenant_admin, hr]
plans: [team, enterprise]
last_reviewed: 2026-07-17
owner: product
internal_spec: ../../internal/product/adaptive-feedback/question-cooldowns.md
---

Internal wiki page contract

Every internal feature specification should include:

• Feature ID and status
• Product intent and non-goals
• Actors and permission checks
• Data classes and privacy boundaries
• Domain model and invariants
• API or event contracts
• UI states and edge cases
• Audit events
• Analytics events
• Failure and recovery behavior
• Test plan
• Migration and rollout
• External documentation link
• Open decisions

Suggested frontmatter:

---
feature_id: CAP-AFF-004
title: Per-question exposure cooldown
status: approved
owners: [product, engineering]
security_review: required
external_doc: ../../../external/product/adaptive-feedback/question-cooldowns.md
adr: ../../adr/ADR-0012-exposure-ledger-scope.md
---

Shared feature index

wiki/shared/feature-index.md is the canonical catalog. Each row must contain:

No capability is considered complete until both wiki links exist or a documented reason explains why one side is not applicable.

Change protocol

For every feature change, Cursor must:

1. Read the shared feature row and both linked pages.
2. Identify whether the change affects claims, user steps, permissions, data, layout, analytics, pricing, or operations.
3. Update the internal specification before or with code.
4. Update the external page whenever observable behavior or user guidance changes.
5. Update the traceability matrix with routes, components, APIs, tests, and analytics events.
6. Add an ADR when the change alters an architectural invariant, security boundary, persistence model, or integration contract.
7. Add release-note content for user-visible changes.
8. Never publish internal implementation details or sensitive operational instructions into the external wiki.

Cursor interaction contract

At the start of each implementation prompt, the agent must report:

• Wiki pages read
• Relevant feature IDs
• Assumptions
• Files expected to change
• Permission and data-visibility impact
• Test plan
• Whether an ADR is required

At the end, it must report:

• Code and content changed
• Tests run and results
• External wiki updates
• Internal wiki updates
• Traceability changes
• Accessibility checks
• Security/privacy checks
• Remaining risks or follow-ups

Source-of-truth rules

• The internal wiki governs domain behavior and invariants.
• The external wiki governs customer-facing language and documented workflows.
• Executable schemas and tests govern exact machine behavior when they disagree with prose; disagreement must create a documentation defect, not silent acceptance.
• Marketing may simplify but must not contradict the external wiki.
• Product UI copy should be reusable from external wiki terminology or a shared copy catalog.
• Imported third-party terminology must be mapped, not allowed to replace native Capablio concepts.