Skip to content

docs(conventions): add the detector-findings owner doc (stub) #2679

Description

@kyle-sexton

Phase 2 of the boris-routines-adoption plan. Depends on #2678.

A hard merge barrier. This must be on main before the Pattern-C pilot opens — a plugin cannot cite a repo-relative docs/conventions/ path, because it installs standalone. The repo's established form is a raw URL to main (plugins/architecture/reference/topic-docs.md:6, and four more), and plugins/skill-quality/scripts/check-skill.sh:480-495 fails broken refs.

Why a stub now rather than the full doc later

docs/PLUGIN-PHILOSOPHY.md:471 — "A new cross-plugin convention lands in an owner doc before a second plugin adopts it." That is a deadline, not a licence to author it late. The pilot phase makes plugins/mutation-testing the second plugin adopting the multi-producer rule, so a stub must precede it. The doc is then hardened from what the pilot observes, which is the real argument for depth trailing the pilot and it survives without :471.

Work items

  • Create docs/conventions/detector-findings/README.md + CHANGELOG.md (the majority sibling shape — 12 of 20 convention directories carry a CHANGELOG).
  • Own the multi-producer rule here, not in a review-plugin context file. PLUGIN-PHILOSOPHY.md:470 is "One owner doc per shared concern", and a rule binding three plugins cannot live inside one of them. feat(review): merge findings across producers and mark consumption explicitly (ADR 0010) #2678's file points here.
  • Fix the four producer-owned fields: machine-computed Tier; Confidence high or omitted — never low, which ranks below absent (findings-normalization.md:62,72); repo-relative file:line Location; cell escaping (a literal pipe written backslash-pipe, newlines as spaces).
  • Cite the findings-file schema by pointer to plugins/review/skills/fanout/context/default-mode.md. Never copy it.
  • Add the row to the convention registry table at PLUGIN-PHILOSOPHY.md:474-499.

Sanity checks

  • ls docs/conventions/detector-findings/README.md docs/conventions/detector-findings/CHANGELOG.md exits 0.
  • grep -c "detector-findings" docs/PLUGIN-PHILOSOPHY.md >= 1.
  • grep -c "^| Rank | Tier | Confidence" docs/conventions/detector-findings/README.md returns 0 — pointer-not-copy; the schema's owner is default-mode.md.
  • gh pr view --json state -q .state on this PR returns MERGED before the pilot phase opens.

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority: needs-triageDefault until a priority tier is assigned.status: readyTriaged, unblocked, and fully specified; eligible to pick up.work-class: structuralRefactors, migrations, contract changes; cross-cutting and hard to reverse.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions