Story Statement
As a maintainer of pair
I want the framework's own skills/guidelines and the pair repo's code to apply the shrink discipline demonstrated by the third-party tools "caveman" (terser agent output) and "ponytail" (less code per task, avoiding over-engineering)
So that pair's own dogfood corpus and codebase stop accumulating unnecessary verbosity in both prose and implementation, and projects adopting pair get a documented, actionable guideline for keeping AI-authored text and code lean
Where: .pair/knowledge/guidelines/technical-standards/ai-development/ (new guideline) + a representative sample under .pair/knowledge//.claude/skills/ (prose) and apps//packages/ (code)
Epic Context
Parent Epic: none — cross-cutting quality/tech-debt concern, standalone (same pattern as #413/#414/#416)
Status: Refined
Priority: P2 (Could-Have)
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:yellow · cost:green
Matrix — per dimension
| Dimension |
Tier |
Source |
Note |
| Service/domain criticality |
green |
Criticality Table (tech/risk-matrix.md) |
Every deployable this story can touch (apps/*, packages/*) is listed Low |
| Change/diff risk |
yellow |
story scope |
Touches multiple, unrelated modules: KB guidelines, .claude/skills mirror, and a representative code sample in apps//packages/ — not schema/migration/contract-breaking |
| Business impact |
yellow |
subdomain classification |
Primary capability touched is Adoption & Guidelines (Supporting) — "develop and maintain guidelines" is its stated key capability; secondary downstream effect on Code & Documentation Generation (Core) noted but not double-counted (per quality-model §3.1, the dimension classifies what the story/diff does, not every subdomain it eventually influences) |
| Security relevance |
green |
path heuristic |
No security-sensitive surface — prose + illustrative code trims only |
| Coupling balance |
not assessed |
no cross-context integration touched |
This story adds no new integration between bounded contexts; map-contexts has nothing to assess |
Tier resolution: max(green, yellow, yellow, green) = yellow. The tier-resolution.default-artifact-downgrade override (risk-matrix.md) does not apply — it downgrades only when every yellow is Service-criticality and/or Business-impact, and here Change/diff-risk is also yellow.
Acceptance Criteria
Functional Requirements
Given-When-Then Format:
-
Given the caveman and ponytail reference tools
When the analysis phase is complete
Then the story's notes/PR description name which specific techniques generalize as a reusable convention (terser output, minimal-diff code, no over-engineering) versus which are tool-specific mechanics that don't apply (proxying, compression internals) — with a one-line rationale per technique
-
Given the new AI-usage guideline
When a maintainer reads .pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md
Then it states the discipline as concrete, actionable rules (default to the smallest correct code/text; prefer what already exists over new abstractions; keep generated prose proportional to what's needed) with at least one before/after example for prose and one for code, and explicitly cross-references ADR-010 principle 4 (Pruning discipline, skills-guide.md §Authoring Standard) as the skill-specific precedent rather than restating it (per ADR-010)
-
Given the guideline is added under .pair/knowledge/guidelines/
When the mirrored dataset counterpart and llms.txt are checked
Then packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md exists and is identical to the root file, the folder's README.md index lists it, and .pair/llms.txt carries its entry (documentation-standards.md indexing rule)
-
Given a representative sample of existing skills/guidelines under .pair/knowledge/ and/or .claude/skills/
When the shrink discipline is applied to at least one file
Then restated context/boilerplate verbosity is removed while every required template section (frontmatter, C/S/A/V pattern, composition table) is preserved and no semantic content is lost
-
Given a representative sample of code under apps/ or packages/
When the shrink discipline is applied to at least one over-built abstraction or restated logic
Then the simplification is behavior-preserving and the existing automated test suite for that module still passes (test-first per the repo's bug-fix workflow only applies if a behavior bug is found and fixed; a pure simplification with no behavior change needs no new test)
-
Given any .pair/knowledge/** file mirrored into .claude/skills/**/.claude/workflows/** (or into packages/knowledge-hub/dataset/.pair/knowledge/**) is edited as part of the representative pass or the new guideline
When the change is committed
Then the mirrored counterpart is updated in the same commit, so mirror-guard/workflow-mirror tests keep passing
Business Rules
- The guideline is qualitative, example-driven guidance, not a hard numeric token/line-count budget (resolves Open Question 2) — a fixed numeric budget would be arbitrary and gameable; before/after examples carry the bar instead, consistent with how the rest of the KB avoids dedicated numeric metrics for judgment calls.
- The new guideline lives at
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md (resolves Open Question 1) — sibling to ai-tools.md/documentation-standards.md, because it is an AI-output-quality rule spanning both prose and code equally, not a code-design-only or QA-only concern, and not a skill-authoring-only concern (that's ADR-010's scope).
- caveman and ponytail are studied as reference points only; neither is added as a dependency (per Initial Scope "Out of Scope").
- The representative pass never removes required structural elements (DoD/AC template sections, skill frontmatter, composition tables) — only restated prose or dead/duplicated code.
Edge Cases and Error Handling
- Invalid Input: n/a — documentation/code-style story, no runtime input surface.
- System Errors: n/a.
- Boundary Conditions: a candidate file already minimal with no trim opportunity — pick a different representative file rather than forcing a trivial edit to satisfy AC4/AC5.
- Exceptional Scenarios: a touched file is part of a guarded mirror pair (AC6) — both sides are edited in the same commit; a touched file is NOT mirrored — edit only that one file.
Definition of Done Checklist
Development Completion
Quality Assurance
Deployment and Release
Story Sizing and Sprint Readiness
Refined Story Points
Final Story Points: L (5)
Confidence Level: Medium (up from Low — scope, guideline location, and the qualitative-vs-numeric question are now resolved; residual uncertainty is only in which representative files best demonstrate the discipline)
Sizing Justification: three distinct phases (analysis of two external tools, a new cross-cutting KB guideline with mirror/index upkeep, and two representative-pass edits across different corpora) justify L over M, but the story stays bounded — no new abstraction, no schema/infra change, no dependency added.
Sprint Capacity Validation
Sprint Fit Assessment: Fits within a single sprint — bounded scope (one guideline + a small representative sample), no blocking dependencies.
Development Time Estimate: ~2 days (analysis + guideline authoring + mirror/index upkeep)
Testing Time Estimate: ~1 day (diff review of representative trims + running existing suites)
Total Effort Assessment: Fits within sprint capacity: Yes
Story Splitting Recommendations
Not needed — story fits in-sprint at its current L(5) size.
Dependencies and Coordination
Story Dependencies
Prerequisite Stories: none
Dependent Stories: none known
Shared Components: .pair/knowledge/ guideline corpus, packages/knowledge-hub mirror mechanism (shared with every other story touching KB content)
Team Coordination
Development Roles Involved:
- Backend/Framework: guideline authoring, representative code-sample simplification
- QA: verify existing test suites and mirror-guard checks still pass after the representative pass
External Dependencies
Third-party Integrations: none — caveman/ponytail are studied, not integrated (Out of Scope)
Infrastructure Requirements: none
Compliance Requirements: none
Validation and Testing Strategy
Acceptance Testing Approach
Testing Methods: manual diff review of the representative before/after edits against AC4/AC5/AC6; running the existing automated suite (unit tests, mirror-guard/workflow-mirror, lint) to confirm no regression.
Test Data Requirements: none — no runtime data involved.
Environment Requirements: local dev environment only.
User Validation
User Feedback Collection: maintainer review of the new guideline + representative diffs during code review.
Success Metrics: guideline merged and indexed; at least one skills/guidelines file and one code file demonstrably leaner with no lost semantics or broken tests.
Rollback Plan: revert the guideline/representative-pass commits — no runtime impact, safe to revert independently.
Notes and Additional Context
Refinement Session Insights: Adoption-informed refinement found ADR-010 (Skill Authoring Effectiveness Standard, principle 4 "Pruning discipline") already codifies this exact discipline for the skills corpus specifically. #433 is scoped to generalize it beyond skills — to plain KB prose and to application code — and must cite/build on ADR-010 rather than re-deriving skill-pruning rules from scratch.
Team Concerns: subjectivity of "unnecessary verbosity" — mitigated by requiring concrete before/after examples in the guideline itself (see Technical Risks).
Future Considerations: a broader corpus-wide pass beyond the representative sample is explicitly Out of Scope for this story and would be a follow-up.
Documentation Links: ADR-010 (.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md), skills-guide.md §Authoring Standard principle 4.
Technical Analysis
Implementation Approach
Technical Strategy: Additive, three-phase pass — (1) analysis note distinguishing generalizable technique from tool-specific mechanics; (2) new guideline file; (3) one representative edit each in the KB/skills corpus and in application code, each verified against existing tests/mirror checks.
Key Components: .pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md (new) + its dataset mirror + index entries (llms.txt, folder README.md); one representative skill/guideline edit; one representative code edit.
Data Flow: n/a — documentation/code-quality change, no runtime data flow.
Integration Points: packages/knowledge-hub dataset-mirror mechanism (guarded by mirror-guard/workflow-mirror tests); .pair/llms.txt index.
Design: not required
Technical Requirements
- New guideline must be indexed (
llms.txt + local README.md) per documentation-standards.md.
- Any
.pair/knowledge/** edit that has a .claude/skills/**/.claude/workflows/** or dataset mirror counterpart must update both in the same commit (mirror-guard invariant, risk-matrix.md change-risk.dataset-mirror-pairs).
- No new abstraction, dependency, or third-party tool integration introduced (Out of Scope boundary).
Technical Risks and Mitigation
| Risk |
Impact |
Probability |
Mitigation Strategy |
| Subjectivity of "unnecessary verbosity" leads to inconsistent trims |
Medium |
Medium |
Ground the guideline in concrete before/after examples and qualitative heuristics rather than vague language (Business Rules above) |
| caveman/ponytail's tool-specific mechanics misread as generalizable convention |
Medium |
Low |
Analysis phase (AC1) explicitly separates generalizable convention from tool-internal mechanics before any guideline text is written |
| Representative-pass edits regress skill/guideline structure or code behavior |
High |
Low |
Preserve required template sections (AC4); existing test suite + mirror-guard must stay green (AC5/AC6) before the edit is considered done |
Spike Requirements
Required Spikes: none — the analysis phase (AC1) is a bounded research task within the story, not a separate spike.
Task Breakdown
Dependency Graph
T-1 ── T-2 ──┬── T-3
├── T-4 ──┐
└── T-5 ──┴── T-6
AC Coverage
| AC |
Tasks |
| AC-1 (analysis: generalizable vs tool-specific) |
T-1 |
| AC-2 (guideline content + ADR-010 citation) |
T-2 |
| AC-3 (mirror + index) |
T-2, T-3 |
| AC-4 (skills/guidelines representative trim) |
T-4, T-6 |
| AC-5 (code representative simplification) |
T-5, T-6 |
| AC-6 (mirror lockstep) |
T-2, T-4, T-6 |
T-1: Analyze caveman and ponytail — generalizable technique vs tool-specific mechanics
Priority: P2 | Estimated Hours: 2h | Bounded Context: Adoption & Guidelines
Summary: Read both tools' READMEs/source at a level sufficient to separate what generalizes (terser agent output, minimal-diff code, anti-over-engineering) from tool-internal mechanics (proxying, compression) that don't apply here.
Type: Research
Acceptance Criteria:
- Primary deliverable: a short list (in the PR description or a working note) naming each generalizable technique and each excluded tool-specific mechanic, one line of rationale each.
- Quality standard: every technique named traces to something observable in the tools' own documented behavior, not assumed.
- Integration requirement: feeds directly into T-2's guideline content.
- Verification method: reviewer can trace each Business Rule/example in T-2 back to a line in this list.
Dependencies: none (first task)
T-2: Author shrink-discipline.md guideline (root + dataset mirror), citing ADR-010
Priority: P2 | Estimated Hours: 3h | Bounded Context: Adoption & Guidelines
Summary: Write the new AI-usage guideline at .pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md, with the mirrored copy at packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md.
Type: Documentation
Acceptance Criteria:
- Primary deliverable: the guideline file (root + dataset mirror, byte-identical), stating the discipline as concrete rules (smallest correct code/text; reuse over new abstraction; proportional prose) with ≥1 before/after example for prose and ≥1 for code.
- Quality standard: explicitly cross-references ADR-010 principle 4 (Pruning discipline) as the skill-specific precedent — does not restate it.
- Integration requirement: sits alongside
ai-tools.md/documentation-standards.md in the same folder, same structure conventions.
- Verification method:
diff between root and dataset-mirror copies is empty.
Files to Create:
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md — new guidelinepackages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md — mirror
Dependencies: T-1 (analysis feeds the content)
T-3: Index the guideline (llms.txt + folder README.md)
Priority: P2 | Estimated Hours: 0.5h | Bounded Context: How-To Knowledge
Summary: Add the new guideline to the discoverability indexes per documentation-standards.md's indexing rule.
Type: Documentation
Acceptance Criteria:
- Primary deliverable:
.pair/llms.txt carries a line for shrink-discipline.md; .pair/knowledge/guidelines/technical-standards/ai-development/README.md lists it.
- Verification method: both files show the new entry; mirrored
llms.txt/README counterpart (if any) updated in the same commit.
Files to Modify:
.pair/llms.txt.pair/knowledge/guidelines/technical-standards/ai-development/README.md
Dependencies: T-2
T-4: Representative trim — one skills/guidelines file
Priority: P2 | Estimated Hours: 2h | Bounded Context: How-To Knowledge / Adoption & Guidelines
Summary: Apply the shrink discipline to one existing file under .pair/knowledge/ and/or .claude/skills/ — remove restated context/boilerplate while preserving every required template section.
Type: Documentation
Acceptance Criteria:
- Primary deliverable: one file with a visible before/after reduction in verbosity, no lost semantic content.
- Quality standard: required structural elements (frontmatter, C/S/A/V pattern, composition tables) untouched.
- Integration requirement: if the file has a
.claude/skills/**/dataset mirror counterpart, both sides updated together (AC6).
- Verification method: reviewer diff shows only prose trims, no removed section headers.
Dependencies: T-2 (discipline defined first)
T-5: Representative simplification — one over-built abstraction in code
Priority: P2 | Estimated Hours: 3h | Bounded Context: Code & Documentation Generation
Summary: Find and simplify one instance of over-built abstraction or restated logic under apps/ or packages/, the way ponytail's before/after examples do — behavior-preserving.
Type: Refactoring
Acceptance Criteria:
- Primary deliverable: one simplified code unit, smaller and equally correct.
- Quality standard: no behavior change; if a real bug is found instead, follow the repo's test-first bug workflow rather than folding it into this task.
- Verification method: existing test suite for the touched module passes unchanged.
Dependencies: T-2
T-6: Verify — mirror-guard/workflow-mirror + existing test suites green, no regressions
Priority: P2 | Estimated Hours: 1h | Bounded Context: Integration & Process Standardization
Summary: Run the full relevant check set after T-2/T-3/T-4/T-5 land: mirror-guard/workflow-mirror tests, lint, and the unit tests for any touched module.
Type: Testing
Acceptance Criteria:
- Primary deliverable: a green run of the above checks.
- Verification method: CI (or local run) output attached/referenced in the PR.
Dependencies: T-4, T-5
Refinement Completed By: pair-process-refine-story (AI-assisted refinement session)
Refinement Date: 2026-08-25
Review and Approval: pending maintainer confirmation (grill sync unavailable in this unattended run — see summary)
Notes
Origin: raised directly by the maintainer while reviewing risk-classification bias and epic hygiene, referencing two installed third-party skills as concrete reference points: "caveman" (github.com/JuliusBrussee/caveman) and "ponytail" (github.com/DietrichGebert/ponytail).
Story Statement
As a maintainer of pair
I want the framework's own skills/guidelines and the pair repo's code to apply the shrink discipline demonstrated by the third-party tools "caveman" (terser agent output) and "ponytail" (less code per task, avoiding over-engineering)
So that pair's own dogfood corpus and codebase stop accumulating unnecessary verbosity in both prose and implementation, and projects adopting pair get a documented, actionable guideline for keeping AI-authored text and code lean
Where:
.pair/knowledge/guidelines/technical-standards/ai-development/(new guideline) + a representative sample under.pair/knowledge//.claude/skills/(prose) andapps//packages/(code)Epic Context
Parent Epic: none — cross-cutting quality/tech-debt concern, standalone (same pattern as #413/#414/#416)
Status: Refined
Priority: P2 (Could-Have)
Status Workflow
Classification
risk:yellow·cost:greenMatrix — per dimension
tech/risk-matrix.md)apps/*,packages/*) is listed Low.claude/skillsmirror, and a representative code sample inapps//packages/— not schema/migration/contract-breakingmap-contextshas nothing to assessTier resolution: max(green, yellow, yellow, green) = yellow. The
tier-resolution.default-artifact-downgradeoverride (risk-matrix.md) does not apply — it downgrades only when every yellow is Service-criticality and/or Business-impact, and here Change/diff-risk is also yellow.Acceptance Criteria
Functional Requirements
Given-When-Then Format:
Given the caveman and ponytail reference tools
When the analysis phase is complete
Then the story's notes/PR description name which specific techniques generalize as a reusable convention (terser output, minimal-diff code, no over-engineering) versus which are tool-specific mechanics that don't apply (proxying, compression internals) — with a one-line rationale per technique
Given the new AI-usage guideline
When a maintainer reads
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.mdThen it states the discipline as concrete, actionable rules (default to the smallest correct code/text; prefer what already exists over new abstractions; keep generated prose proportional to what's needed) with at least one before/after example for prose and one for code, and explicitly cross-references ADR-010 principle 4 (Pruning discipline,
skills-guide.md§Authoring Standard) as the skill-specific precedent rather than restating it (per ADR-010)Given the guideline is added under
.pair/knowledge/guidelines/When the mirrored dataset counterpart and
llms.txtare checkedThen
packages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.mdexists and is identical to the root file, the folder'sREADME.mdindex lists it, and.pair/llms.txtcarries its entry (documentation-standards.md indexing rule)Given a representative sample of existing skills/guidelines under
.pair/knowledge/and/or.claude/skills/When the shrink discipline is applied to at least one file
Then restated context/boilerplate verbosity is removed while every required template section (frontmatter, C/S/A/V pattern, composition table) is preserved and no semantic content is lost
Given a representative sample of code under
apps/orpackages/When the shrink discipline is applied to at least one over-built abstraction or restated logic
Then the simplification is behavior-preserving and the existing automated test suite for that module still passes (test-first per the repo's bug-fix workflow only applies if a behavior bug is found and fixed; a pure simplification with no behavior change needs no new test)
Given any
.pair/knowledge/**file mirrored into.claude/skills/**/.claude/workflows/**(or intopackages/knowledge-hub/dataset/.pair/knowledge/**) is edited as part of the representative pass or the new guidelineWhen the change is committed
Then the mirrored counterpart is updated in the same commit, so
mirror-guard/workflow-mirrortests keep passingBusiness Rules
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md(resolves Open Question 1) — sibling toai-tools.md/documentation-standards.md, because it is an AI-output-quality rule spanning both prose and code equally, not a code-design-only or QA-only concern, and not a skill-authoring-only concern (that's ADR-010's scope).Edge Cases and Error Handling
Definition of Done Checklist
Development Completion
packages/knowledge-hubmirror tests (mirror-guard/workflow-mirror) pass for any touched dataset pairllms.txt+ folderREADME.mdindex entries for the new guidelineQuality Assurance
Deployment and Release
main(KB/code change, no separate deploy/staging step)Story Sizing and Sprint Readiness
Refined Story Points
Final Story Points: L (5)
Confidence Level: Medium (up from Low — scope, guideline location, and the qualitative-vs-numeric question are now resolved; residual uncertainty is only in which representative files best demonstrate the discipline)
Sizing Justification: three distinct phases (analysis of two external tools, a new cross-cutting KB guideline with mirror/index upkeep, and two representative-pass edits across different corpora) justify L over M, but the story stays bounded — no new abstraction, no schema/infra change, no dependency added.
Sprint Capacity Validation
Sprint Fit Assessment: Fits within a single sprint — bounded scope (one guideline + a small representative sample), no blocking dependencies.
Development Time Estimate: ~2 days (analysis + guideline authoring + mirror/index upkeep)
Testing Time Estimate: ~1 day (diff review of representative trims + running existing suites)
Total Effort Assessment: Fits within sprint capacity: Yes
Story Splitting Recommendations
Not needed — story fits in-sprint at its current L(5) size.
Dependencies and Coordination
Story Dependencies
Prerequisite Stories: none
Dependent Stories: none known
Shared Components:
.pair/knowledge/guideline corpus,packages/knowledge-hubmirror mechanism (shared with every other story touching KB content)Team Coordination
Development Roles Involved:
External Dependencies
Third-party Integrations: none — caveman/ponytail are studied, not integrated (Out of Scope)
Infrastructure Requirements: none
Compliance Requirements: none
Validation and Testing Strategy
Acceptance Testing Approach
Testing Methods: manual diff review of the representative before/after edits against AC4/AC5/AC6; running the existing automated suite (unit tests,
mirror-guard/workflow-mirror, lint) to confirm no regression.Test Data Requirements: none — no runtime data involved.
Environment Requirements: local dev environment only.
User Validation
User Feedback Collection: maintainer review of the new guideline + representative diffs during code review.
Success Metrics: guideline merged and indexed; at least one skills/guidelines file and one code file demonstrably leaner with no lost semantics or broken tests.
Rollback Plan: revert the guideline/representative-pass commits — no runtime impact, safe to revert independently.
Notes and Additional Context
Refinement Session Insights: Adoption-informed refinement found ADR-010 (Skill Authoring Effectiveness Standard, principle 4 "Pruning discipline") already codifies this exact discipline for the skills corpus specifically. #433 is scoped to generalize it beyond skills — to plain KB prose and to application code — and must cite/build on ADR-010 rather than re-deriving skill-pruning rules from scratch.
Team Concerns: subjectivity of "unnecessary verbosity" — mitigated by requiring concrete before/after examples in the guideline itself (see Technical Risks).
Future Considerations: a broader corpus-wide pass beyond the representative sample is explicitly Out of Scope for this story and would be a follow-up.
Documentation Links: ADR-010 (
.pair/adoption/tech/adr/adr-010-skill-authoring-effectiveness-standard.md),skills-guide.md§Authoring Standard principle 4.Technical Analysis
Implementation Approach
Technical Strategy: Additive, three-phase pass — (1) analysis note distinguishing generalizable technique from tool-specific mechanics; (2) new guideline file; (3) one representative edit each in the KB/skills corpus and in application code, each verified against existing tests/mirror checks.
Key Components:
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md(new) + its dataset mirror + index entries (llms.txt, folderREADME.md); one representative skill/guideline edit; one representative code edit.Data Flow: n/a — documentation/code-quality change, no runtime data flow.
Integration Points:
packages/knowledge-hubdataset-mirror mechanism (guarded bymirror-guard/workflow-mirrortests);.pair/llms.txtindex.Design: not required
Technical Requirements
llms.txt+ localREADME.md) perdocumentation-standards.md..pair/knowledge/**edit that has a.claude/skills/**/.claude/workflows/**or dataset mirror counterpart must update both in the same commit (mirror-guard invariant, risk-matrix.mdchange-risk.dataset-mirror-pairs).Technical Risks and Mitigation
Spike Requirements
Required Spikes: none — the analysis phase (AC1) is a bounded research task within the story, not a separate spike.
Task Breakdown
shrink-discipline.mdguideline (root + dataset mirror), citing ADR-010llms.txt+ folderREADME.md).pair/knowledge//.claude/skills/apps//packages/Dependency Graph
AC Coverage
T-1: Analyze caveman and ponytail — generalizable technique vs tool-specific mechanics
Priority: P2 | Estimated Hours: 2h | Bounded Context: Adoption & Guidelines
Summary: Read both tools' READMEs/source at a level sufficient to separate what generalizes (terser agent output, minimal-diff code, anti-over-engineering) from tool-internal mechanics (proxying, compression) that don't apply here.
Type: Research
Acceptance Criteria:
Dependencies: none (first task)
T-2: Author
shrink-discipline.mdguideline (root + dataset mirror), citing ADR-010Priority: P2 | Estimated Hours: 3h | Bounded Context: Adoption & Guidelines
Summary: Write the new AI-usage guideline at
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md, with the mirrored copy atpackages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md.Type: Documentation
Acceptance Criteria:
ai-tools.md/documentation-standards.mdin the same folder, same structure conventions.diffbetween root and dataset-mirror copies is empty.Files to Create:
.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md— new guidelinepackages/knowledge-hub/dataset/.pair/knowledge/guidelines/technical-standards/ai-development/shrink-discipline.md— mirrorDependencies: T-1 (analysis feeds the content)
T-3: Index the guideline (
llms.txt+ folderREADME.md)Priority: P2 | Estimated Hours: 0.5h | Bounded Context: How-To Knowledge
Summary: Add the new guideline to the discoverability indexes per
documentation-standards.md's indexing rule.Type: Documentation
Acceptance Criteria:
.pair/llms.txtcarries a line forshrink-discipline.md;.pair/knowledge/guidelines/technical-standards/ai-development/README.mdlists it.llms.txt/README counterpart (if any) updated in the same commit.Files to Modify:
.pair/llms.txt.pair/knowledge/guidelines/technical-standards/ai-development/README.mdDependencies: T-2
T-4: Representative trim — one skills/guidelines file
Priority: P2 | Estimated Hours: 2h | Bounded Context: How-To Knowledge / Adoption & Guidelines
Summary: Apply the shrink discipline to one existing file under
.pair/knowledge/and/or.claude/skills/— remove restated context/boilerplate while preserving every required template section.Type: Documentation
Acceptance Criteria:
.claude/skills/**/dataset mirror counterpart, both sides updated together (AC6).Dependencies: T-2 (discipline defined first)
T-5: Representative simplification — one over-built abstraction in code
Priority: P2 | Estimated Hours: 3h | Bounded Context: Code & Documentation Generation
Summary: Find and simplify one instance of over-built abstraction or restated logic under
apps/orpackages/, the way ponytail's before/after examples do — behavior-preserving.Type: Refactoring
Acceptance Criteria:
Dependencies: T-2
T-6: Verify — mirror-guard/workflow-mirror + existing test suites green, no regressions
Priority: P2 | Estimated Hours: 1h | Bounded Context: Integration & Process Standardization
Summary: Run the full relevant check set after T-2/T-3/T-4/T-5 land:
mirror-guard/workflow-mirrortests, lint, and the unit tests for any touched module.Type: Testing
Acceptance Criteria:
Dependencies: T-4, T-5
Refinement Completed By: pair-process-refine-story (AI-assisted refinement session)
Refinement Date: 2026-08-25
Review and Approval: pending maintainer confirmation (grill sync unavailable in this unattended run — see summary)
Notes
Origin: raised directly by the maintainer while reviewing risk-classification bias and epic hygiene, referencing two installed third-party skills as concrete reference points: "caveman" (github.com/JuliusBrussee/caveman) and "ponytail" (github.com/DietrichGebert/ponytail).