Skip to content

engineering-principles.md restates facts owned by PROFILES.md (DRY drift) #58

Open

Description

@cacack

docs/engineering-principles.md restates two facts that principles/PROFILES.md owns:

  • the profile registry paths (which payload installs to which target)
  • the legacy block ID

Both are accurate today. Both will drift the moment the contract changes and only one file gets updated — and the doc is the copy a reader is more likely to trust, since it is the narrative entry point.

This is the canon's own "Don't repeat knowledge (DRY) — every fact and rule has one authoritative home" applied to the kit that ships it. Worth fixing for the same reason the change that surfaced it was worth making: the delivery mechanism should obey the canon it delivers.

Found by the verification pass in the v2.0.0 profile split (/play batch, prompt 007, finding 4).

Suggested approach

Replace the restated specifics with a pointer to PROFILES.md, keeping the doc's explanatory prose about why two profiles exist. The narrative is the doc's job; the lookup table is the contract's.

Acceptance criteria

  • docs/engineering-principles.md states registry paths and the legacy ID zero times, linking PROFILES.md instead
  • The doc still reads as a complete explanation — a reader learns why there are two audiences and what happens on re-sync without needing the contract open
  • No other file restates the registry or the legacy ID (sweep, don't assume)

Files

Paths corrected during triage, 2026-09-11. This issue was filed against the
pre-split layout; plugins/cacack/ no longer exists. Both files moved to
plugins/principles/ in a8540c8 (the five-plugin split). Substance unchanged —
see the triage comment for what is still true.

Activity

  1. added
    type:taskPredefined, procedure-backed work
    class:unplannedWork that arrived; never milestoned
    on Sep 11, 2026
  2. cacack commented on Sep 11, 2026

    @cacack
    OwnerAuthor

    Generated by Claude Code.

    Triage, 2026-09-11 — surfaced by the untriaged-queue query in issue-standards (an issue carrying no class: label) after the 2026-09-11 panel-product run flagged un-sequenced backlog.

    Labels added: type:task, class:unplanned. Unplanned because it arrived from the v2.0.0 verification pass rather than being chosen — so it correctly carries no milestone. Type is a close call: the approach is already decided in the issue body and the criteria are mechanical, which reads as Task; if you consider the "what stays as narrative, what becomes a link" judgement to be real design latitude, it is a Story. Flip it if you disagree.

    Stale references corrected (structure, not substance). The issue was filed against the pre-split layout and both cited paths were gone:

    Cited Now
    plugins/cacack/docs/engineering-principles.md plugins/principles/docs/engineering-principles.md
    plugins/cacack/principles/PROFILES.md plugins/principles/principles/PROFILES.md

    Both moved in a8540c8 (five-plugin split). The Files section now points at the real paths, with a note recording the correction.

    What is still true — the issue is valid but narrower than filed. It names two restated facts:

    1. Registry paths — appears already resolved. engineering-principles.md:5 now links to PROFILES.md as "the contract that binds them" rather than restating the payload/target table. The table lives only in PROFILES.md:11-14.
    2. Legacy block ID — still drifting. engineering-principles.md:37 restates the legacy block ID engineering-kit:instill-principles and both of its locations (.claude/rules/engineering-kit.md, repo-root CLAUDE.md). PROFILES.md:53-60 owns exactly that, including the scope→location table. This is the duplication the issue is about, and it is the one still standing.

    So acceptance criterion 1 is roughly half met already. Criterion 3 ("no other file restates the registry or the legacy ID — sweep, don't assume") has not been checked in this triage and still stands.

    Not re-scoped. Narrowing this to the legacy-ID duplication alone is your call, not mine — raising it here per the standard's "flag a re-scope instead of performing it".

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

    class:unplannedWork that arrived; never milestoneddocumentationImprovements or additions to documentationeffort:lowLow implementation effortpriority:lowLow prioritytype:taskPredefined, procedure-backed workvalue:lowLow user value

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions