Team Workflow

The wiki works best when the whole team maintains it. This guide covers ownership conventions, PR workflow, conflict resolution, and how to keep the wiki healthy over time.

Who Maintains the Wiki

Everyone on the team contributes, following domain ownership. The person who knows a domain best is responsible for reviewing changes to that domain's memory items. In practice:

The developer who discovers a new exception or business rule adds it as a memory item.
The domain expert confirms items during code review.
Anyone can deprecate items they know are outdated.
There is no single "wiki maintainer" role. Ownership is distributed.

PR Conventions

When a PR includes wiki changes, follow these conventions to keep reviews smooth:

Situation	Convention
Adding a new memory item	Include in the same PR as the code change that motivated it. Tag the domain expert as reviewer.
Updating an existing item	Explain why in the PR description. Link to the code change that invalidated the previous version.
Deprecating an item	Deprecate in the same PR that removes or changes the related code. Never delete items, deprecate them.
Wiki-only changes	Separate PR with a `wiki:` prefix in the title (e.g., "wiki: confirm billing items").

When to Promote, Confirm, Deprecate

Action	When
`promote`	A candidate looks accurate and useful. You have verified it against the code.
`confirm`	During code review, you verified that an item is still accurate. Especially useful for items at `seen-in-code` or `inferred` confidence.
`deprecate`	The code changed and the item is no longer relevant. The exception was fixed, the rule was removed, or the decision was reversed.

Handling Merge Conflicts in .wiki/

Since .wiki/ files are YAML, merge conflicts are usually straightforward:

Two new items added to the same domain — keep both, ensure unique IDs.
Same item updated by two people — take the most recent or most accurate version. Check dates.
One branch deprecates, another updates — check which is correct against the current code.

After resolving conflicts, always run codefidence validate to ensure the YAML is valid and all items are consistent.

Preventing Wiki Debt

Wiki debt is when memory items drift out of sync with the code. Prevention is easier than cleanup:

Run validate in CI — catch stale or broken items before they merge.
Keep items concrete — "Never call X without Y" is better than "Be careful with X". Vague items rot faster.
Deprecate, don't delete — deprecated items serve as historical context. Deletion loses that context permanently.
Review stale items weekly — run codefidence validate once a week and either confirm or deprecate flagged items.

Minimal CI Setup

Add wiki validation to your CI pipeline so broken or stale items block merges:

GitHub Actions

.github/workflows/wiki.yml

name: Wiki Validation
on: [pull_request]

jobs:
  wiki-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install codefidence
        run: npm install -g @agence-debord/codefidence
      - name: Validate wiki
        run: codefidence validate --strict
      - name: Check diff against wiki
        run: codefidence check-diff --pr-comment

GitLab CI

.gitlab-ci.yml

wiki-validation:
  stage: test
  script:
    - npm install -g @agence-debord/codefidence
    - codefidence validate --strict
    - codefidence check-diff --pr-comment
  only:
    - merge_requests

The --strict flag makes validate exit with a non-zero code if any items are invalid or stale, which fails the CI job. The --pr-comment flag formats check-diff output as GitHub PR comment markdown (silent when sensitivity is low).