tech-debt: relocate skill-conventions/ into guidelines (technical-standards/ai-development)

[rucka]

Resolution

Delivered by PR #370 (merged). Board: Done.

refactor: relocate skill-conventions into guidelines (technical-standards/ai-development).

Story Statement

As a maintainer of the Pair KB
I want the skill-conventions/ files relocated from the .pair/knowledge/ root into guidelines/technical-standards/ai-development/skill-conventions/ (folder kept cohesive), with every reference rewritten and the section registered in the guidelines catalogs
So that these single-source skill-corpus conventions live where guidelines belong — catalogued, discoverable, registered — instead of as a loose top-level folder that reads as "guidelines dumped at the root"

Where: the KB (packages/knowledge-hub/dataset/.pair/knowledge/** + the generated root mirror .pair/knowledge/ and .claude/skills/**), the docs-site guidelines catalog (apps/website/content/docs/reference/guidelines-catalog.mdx), and one conformance test.

Epic Context

Parent Epic: None — standalone tech-debt / KB-structure hygiene. Closest precedent is #223 ("consolidate design rules into code-design guidelines") under #209 — same consolidate-into-the-right-guidelines-section move; if an epic is required, #209 is the least-bad fit. Lineage: extends #313 (skill-corpus dedup, closed), which created these files at the root.
Status: Refined
Priority: P1 (Should-Have) — active structural inconsistency (guidelines-in-substance living outside guidelines/), not a hypothetical gap.

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Classification

risk:red · cost:green — pure relocation of a cohesive KB section, but the link-rewrite blast radius spans the whole skill layer: 39 dataset SKILL.md + 39 root-mirror copies + 2 non-skill refs, dataset↔root byte-consistency. Core deliverable (the skill/KB layer), no security surface, no content change (refinement).

Classification matrix — per dimension

Dimension	Tier	Source	Note
Service/domain criticality	yellow	KB default (no Criticality Table in tech/risk-matrix.md)	Medium default — file present, criticality table absent (quality-model §3.1)
Change/diff risk	yellow	story scope	touches shared code corpus-wide (39 SKILL.md × dataset+mirror ≈ 78 files + 9 moved files + 2 non-skill refs + 3 catalogs) — but mechanical relocation + path substitution, NOT schema/migration/contract-breaking
Business impact	red	subdomain class	core — the skill/KB layer is Pair's core deliverable
Security relevance	green	path heuristic	pure file relocation + link rewrite; no authn/authz/secrets/PII/untrusted input
Coupling balance	not assessed	no DDD subdomain/bounded-context artifacts (refinement)	excluded from the max (quality-model §3.1, D21)

Tier = max(assessed) = risk:red (Business impact). Cost = highest detected signal = green (no cost signals). Model: KB defaults + Tag Projection (Active: risk). Confidence: high.

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given the KB after this story merges (dataset + regenerated root mirror)
   When the repo is grepped for the old path string skill-conventions used as a root-level path (.pair/knowledge/skill-conventions/, including markdown links, prose mentions, and hardcoded test/source constants)
   Then zero occurrences of the old root path remain — every hit resolves under guidelines/technical-standards/ai-development/skill-conventions/ instead (grep-clean, dataset + root).

2. Given the 39 SKILL.md files that point at a convention file, plus the 2 non-skill references (writing-skills.mdx prose, to-issues-triage.test.ts path constant)
   When pair update regenerates the root mirror and pnpm --filter knowledge-hub check:links runs over both the dataset and the root .pair/knowledge trees
   Then every pointer resolves (check:links green on both roots), the root mirror is byte-consistent with the dataset transform, and the to-issues-triage conformance test passes against the new path.

3. Given the relocated section
   When a reader browses the guidelines catalogs
   Then skill-conventions/ is registered in three places: the ai-development/README.md "Standards and Guidelines" list, the guidelines/README.md Technical Standards catalog, and the docs-site guidelines-catalog.mdx Technical Standards table.

4. Given the 9 convention files + their README (10 files total)
   When the move completes
   Then their content is byte-identical to before the move (pure relocation + re-linking — a git diff --stat after normalizing paths shows renames only, no content edits inside the convention files, and their intra-folder sibling links are unchanged because the folder moved cohesively).

Business Rules

• Folder kept cohesive: the whole skill-conventions/ directory moves as a unit — sibling links between convention files stay relative and untouched.
• Rewrite through the copy-pipeline transform, not by hand (D-fix: make pair update self-consistent for the dogfooded root install #346 lineage): the pointer rewrite is authored in dataset canonical form; the root mirror's ../ depth is reconciled by the link-rewriter during pair update. This is the same rewrite class that produced the drift pair update fixed in fix: make pair update self-consistent for the dogfooded root install #346 — link-integrity is the real work.
• No content change: this is relocation + re-linking only. Any convention-text edit is out of scope.

Edge Cases and Error Handling

• Prose / non-link references: writing-skills.mdx:141 names the path in prose; to-issues-triage.test.ts:10 hardcodes it as a path constant. Grep-clean (AC1) must cover these, not only markdown-link occurrences.
• next/SKILL.md depth outlier: in the dataset this one file links at ../../ (depth 2) while the other 38 use ../../../ (depth 3); in the root mirror all are ../../../ (flat pair-* layout). This is precisely why the rewrite must NOT hand-count ../ — the tail is substituted in dataset canonical form and pair update's link-rewriter fixes the per-file mirror depth.
• skills-guide.md sibling smell: also a loose top-level file — explicitly out of scope, flag as a follow-up story (do not fold it in here).

Definition of Done Checklist

• All 4 acceptance criteria met and verified
• skill-conventions/ relocated cohesively under guidelines/technical-standards/ai-development/ (dataset), root mirror regenerated via pair update
• 39 dataset SKILL.md pointers + 2 non-skill refs rewritten to the new path
• Registered in ai-development README, guidelines catalog, docs-site catalog
• Grep-clean of the old root path (dataset + root, incl. prose + test constant)
• check:links green on both dataset and root trees; mirror byte-consistent; conformance suite green
• No content change inside the moved convention files (renames only)
• Follow-up story filed for skills-guide.md relocation
• PR reviewed and merged (risk:red → 1 reviewer, explicit approval, 2-day SLA)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: High
Sizing Justification: Wide file breadth (≈78 mirror-inclusive files) but the change is mechanical and deterministic — a cohesive git mv, a tail path-substitution authored in dataset canonical form, pair update to regenerate the mirror, 3 small catalog edits, 2 non-skill ref fixes. No new mechanism, no behavior change, no conceptual complexity (unlike #314's 3-pt template-resolution logic). Risk sits entirely in link-integrity, which is fully verifiable by check:links + grep + the conformance test. Breadth is offset by scriptability → M.

Sprint Capacity Validation

Sprint Fit Assessment: fits in one sprint / one PR.
Development Time Estimate: ~1 day.
Testing Time Estimate: ~0.25 day (grep-clean + check:links + conformance run).
Total Effort Assessment: Fits within sprint capacity: Yes.

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: #314 (template-override wiring) — informational mutex, not a logical dependency. Both #314 and #365 rewrite many of the same SKILL.md files; running them in parallel risks conflicting/overwritten merges on the shared skill layer. #365 queues behind #314 on the skill layer and rebases onto the #314-merged state (same wide-mutex constraint noted for #314's own T3).
Dependent Stories: none.
Follow-up spawned: skills-guide.md relocation (sibling smell, out of scope here).
Shared Components: the 39 SKILL.md files; the copy-pipeline link-rewriter (packages/content-ops/src/ops/link-rewriter.ts); check-broken-links (gates both roots); to-issues-triage.test.ts conformance test.

External Dependencies

None — no third-party, infra, or compliance coordination. No CLI/install-code change (the link-rewriter already handles the transform).

Validation and Testing Strategy

Testing Methods: (1) grep-clean assertion for the old root path across dataset + root, including prose and the test constant; (2) pnpm --filter knowledge-hub check:links green on both dataset and root .pair/knowledge trees; (3) mirror byte-consistency check (pair update re-run yields no diff); (4) the to-issues-triage conformance test passes against the relocated README; (5) git diff confirms renames only inside the moved folder.
Test Data Requirements: none — validation is over the KB itself.
Environment Requirements: local build + pair update.

Notes and Additional Context

Refinement Session Insights: design decisions were pinned before refinement (target sub-path, cohesive move, rewrite-through-pipeline, skills-guide deferred, pure relocation). Grill confirmed them and surfaced two blast-radius items the original draft missed: the writing-skills.mdx prose reference and — most importantly — the to-issues-triage.test.ts conformance test that hardcodes the dataset path (DATASET_CONVENTIONS) and would break if not updated. Also confirmed: the dataset rewrite is a tail-substitution (.pair/knowledge/skill-conventions/ → .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/); the ../ prefix depth to .pair/knowledge/ is unchanged in the dataset (skill files don't move) — the mirror depth is the link-rewriter's job on pair update.
Future Considerations: skills-guide.md relocation follow-up.
Documentation Links: .pair/knowledge/guidelines/quality-assurance/quality-model.md (classification); packages/content-ops/src/ops/link-rewriter.ts (rewrite transform); packages/knowledge-hub/src/tools/check-broken-links.ts (dual-root gate).

Technical Analysis

Implementation Approach

Technical Strategy: cohesive git mv of the dataset folder into the target section, a deterministic path-substitution of the old path string in the 39 SKILL.md + 2 non-skill refs (authored in dataset canonical form), catalog registration in 3 places, then pair update to regenerate the root mirror with the link-rewriter reconciling per-file ../ depth. Verify link-integrity end-to-end.
Key Components: packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions/** (source, 10 files — 9 convention files + README); the 39 dataset SKILL.md pointers (128 link occurrences at ../../../ + 1 at ../../); the generated root mirror (.pair/knowledge/ + .claude/skills/**, 99+ occurrences); apps/website/content/docs/contributing/writing-skills.mdx (prose ref); packages/knowledge-hub/src/conformance/to-issues-triage.test.ts (path constant + registration assertion); 3 catalogs (ai-development/README.md, guidelines/README.md, guidelines-catalog.mdx).
Data Flow: dataset canonical form → pair update (flatten/prefix copy + link-rewriter) → root mirror. All rewrites land in the dataset; the root is never edited by hand.
Integration Points: none beyond the KB and copy-pipeline — no CLI/install-code change.
Design: not required — approach is fully understood; no design doc/spike needed.

Technical Requirements

• Rewrite authored in dataset canonical form only; root regenerated, never hand-edited (byte-consistency requirement).
• Zero content change inside the 9 moved files (renames only).
• Grep-clean must cover markdown links, prose, and source/test constants.

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation
Wide-mutex clash with #314 (shared SKILL.md set)	Medium	Certain if run in parallel	Queue behind #314; rebase onto #314-merged state (T-sequencing)
Missed non-link reference (prose / test constant) leaves old path dangling	Medium	Medium	Grep-clean over the raw path string across ALL file types, not just markdown links (AC1) — conformance test is the backstop
Mirror depth mishandled if ../ hand-counted	Medium	Low	Substitute the tail in dataset canonical form; let pair update's link-rewriter fix mirror depth; check:links on both roots is the gate
check:links red on root but green on dataset (drift, à la #346)	High	Low	pair update regenerates before checking; dual-root check:links gates the build

Task Breakdown

Tasks inline per the task-template. One PR. Sequenced after #314 merges (shared-skill-layer mutex).

Checklist

• T1 — Cohesive git mv of skill-conventions/ into ai-development/ (dataset)
• T2 — Rewrite the 39 SKILL.md pointers + 2 non-skill refs (dataset canonical form)
• T3 — Register the section in the 3 catalogs
• T4 — pair update + full link-integrity verification (grep-clean, dual-root check:links, mirror byte-consistency, conformance)

Dependency Graph

T1 ─┬─► T2 ─┐
    └─► T3 ─┴─► T4
(all after #314 merges — shared-skill-layer mutex, sequenced by TIME)

AC Coverage

Task	AC1	AC2	AC3	AC4
T1				✓
T2	✓	✓		✓
T3			✓
T4	✓	✓		✓

Detailed Tasks

T1 — Cohesive move (dataset)

Task Information — Priority: P1 · Est: 0.25d · Bounded Context: Adoption & Guidelines (KB)
Type: Refactoring
Description: git mv packages/knowledge-hub/dataset/.pair/knowledge/skill-conventions packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions — the whole folder (9 convention files + README, 10 files total) as a unit. Intra-folder sibling links stay relative and are unaffected. No content edits.
Acceptance Criteria: AC4 — folder relocated cohesively, git diff shows renames only.
Files to Modify: the 10 files under dataset/.pair/knowledge/skill-conventions/ (rename).
Dependencies: #314 merged.
Testing: git status shows renames; git diff -M shows no content change.

T2 — Rewrite pointers + non-skill refs (dataset canonical form)

Task Information — Priority: P1 · Est: 0.5d · Bounded Context: Adoption & Guidelines (skills)
Type: Refactoring
Description: Substitute the old path tail .pair/knowledge/skill-conventions/ → .pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/ in the 39 dataset SKILL.md files (128 + 1 link occurrences), authored in dataset canonical form (do NOT hand-count ../). Also fix the 2 non-skill refs: writing-skills.mdx:141 (prose) and to-issues-triage.test.ts:10 (DATASET_CONVENTIONS constant). Root mirror is NOT touched here — T4 regenerates it.
Acceptance Criteria: AC1, AC2, AC4 — old root path gone from dataset; pointers correct in canonical form.
Files to Modify: 39 dataset/.skills/**/SKILL.md; apps/website/content/docs/contributing/writing-skills.mdx; packages/knowledge-hub/src/conformance/to-issues-triage.test.ts.
Dependencies: T1.
Testing: grep-clean of old path in dataset + src + docs.

T3 — Register in catalogs

Task Information — Priority: P1 · Est: 0.25d · Bounded Context: Adoption & Guidelines (KB)
Type: Documentation
Description: Add skill-conventions/ to (1) ai-development/README.md "Standards and Guidelines" list, (2) guidelines/README.md Technical Standards catalog bullet under AI Development, (3) docs-site guidelines-catalog.mdx Technical Standards table row. Content sourced from the section README; no new prose invented beyond the catalog entry.
Acceptance Criteria: AC3.
Files to Modify: dataset/.pair/knowledge/guidelines/technical-standards/ai-development/README.md; dataset/.pair/knowledge/guidelines/README.md; apps/website/content/docs/reference/guidelines-catalog.mdx.
Dependencies: T1.
Testing: catalog entries resolve; link check.

T4 — pair update + link-integrity verification

Task Information — Priority: P1 · Est: 0.25d · Bounded Context: Adoption & Guidelines (KB + pipeline)
Type: Verification
Description: Run pair update to regenerate the root mirror (.pair/knowledge/ + .claude/skills/**) via the link-rewriter. Then verify: (a) grep-clean of the old root path across dataset + root (incl. prose/test constant); (b) pnpm --filter knowledge-hub check:links green on BOTH dataset and root trees; (c) mirror byte-consistency (re-running pair update yields no diff); (d) the to-issues-triage conformance test + full knowledge-hub suite green.
Acceptance Criteria: AC1, AC2, AC4.
Files to Modify: generated root mirror (via pair update, not by hand).
Dependencies: T2, T3.
Testing: grep-clean; dual-root check:links; pnpm --filter knowledge-hub test.

---

Refinement Completed By: AI-assisted refinement (Pair /pair-process-refine-story + /pair-process-plan-tasks)
Refinement Date: 2026-07-23
Review and Approval: pending product-owner confirmation

[rucka]

Delivered by PR #370 (merged, main fa28835): skill-conventions relocated to guidelines/technical-standards/ai-development/skill-conventions/ (dataset + root mirror), all 78 SKILL.md pointers + 4 non-link refs (2 docs + 2 test constants) rewritten, registered in the guidelines + ai-development catalogs, mirror regenerated via pair update. Review: ready-for-merge, 0 actionable findings. skills-guide.md fold-in left as a separate follow-up (out of scope).