Skip to content

Restructure repo docs/ with technical focus and .pair/ links #94

Closed as not planned
Closed as not planned
Restructure repo docs/ with technical focus and .pair/ links#94
Labels
user storyWork item representing a user story

Description

@rucka
rucka
opened on Dec 17, 2025

Story Statement

As a maintainer, advanced user, or performance engineer
I want specialized technical documentation organized in repo docs/ with clear links to authoritative .pair/ content
So that I can access deep technical details (customization APIs, performance specs, release process) without duplicating information across the codebase

Where: Repository docs/ folder structure and package README files

Epic Context

Parent Epic: Enhanced CLI Packaging & Distribution #65
Status: Refined
Priority: P0 (Must-Have) - Current documentation is scattered and duplicated, critical for maintainability

Status Workflow

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

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

  1. Given a developer searches for pair-cli internals documentation to contribute
    When they navigate to docs/customization/README.md
    Then they find architecture overview with "📖 Detailed documentation" links to .pair/knowledge/guidelines/ for implementation details

  2. Given a developer wants to add a custom command to pair CLI
    When they read docs/customization/extension-points.md
    Then they find pattern overview with concrete examples and links to .pair/knowledge/guidelines/architecture/ for detailed architecture

  3. Given a user experiences performance issues with KB downloads
    When they read docs/performance/optimization.md
    Then they find caching strategy recommendations and links to HTTP resume ADR in .pair/adoption/tech/adr/

  4. Given a maintainer needs to execute a release
    When they access docs/maintainers/release-process.md
    Then they find complete 3-phase workflow instructions (version → tag → release) without changelog history混入

  5. Given a maintainer searches for architecture decisions
    When they read docs/maintainers/README.md
    Then they find organized links to all .pair/adoption/tech/ content (architecture, infrastructure, tech-stack, ADRs, bounded contexts)

  6. Given a user wants to see release notes and version history
    When they open docs/RELEASE.md
    Then they find only changelog entries and feature descriptions, with release process instructions moved to maintainers section

  7. Given a developer reads @foomakers/pair-cli package README
    When they look for detailed usage guides
    Then they find quick feature list, installation methods, and link to docs/cli/commands.md for comprehensive command reference (no long guides duplicated inline)

Business Rules

  • Link Format Standard: All links to .pair/ use format: 📖 **Detailed documentation**: [Title](../../.pair/path/to/file.md)
  • Content Priority: .pair/ is source of truth; docs/ provides 2-3 paragraph overview + navigation links
  • No Duplication: If content exists in both docs/ and .pair/, remove from docs/ and add link to .pair/
  • README Cleanup: Package READMEs contain only quick start (1-2 commands), feature bullets, installation methods, and link to docs/cli/commands.md
  • RELEASE.md Split: Changelog/version history stays in docs/RELEASE.md; release process workflow moves to docs/maintainers/release-process.md
  • Getting Started Preserved: docs/getting-started/ remains for user onboarding (managed by Story KB Source Documentation & CLI Reference #90), no duplication with customization section
  • CLI Reference Separation: User-facing CLI docs go to docs/cli/ (Story KB Source Documentation & CLI Reference #90), contributor/architecture docs go to docs/customization/ (this story)

Edge Cases and Error Handling

  • Broken .pair/ Links: If link target doesn't exist in .pair/, create placeholder in docs/ with "TODO: create authoritative content in .pair/"
  • Missing Performance Specs: If no performance ADRs exist in .pair/adr/, docs/performance/optimization.md contains inline guidance without links
  • Story KB Source Documentation & CLI Reference #90 Coordination: docs/cli/ and docs/specs/ created by Story KB Source Documentation & CLI Reference #90 are not modified by this story; docs/getting-started/ reorganized by Story KB Source Documentation & CLI Reference #90 T-7
  • Relative Path Resolution: All links use ../../.pair/ format from docs/ subdirectories to ensure paths work regardless of browsing context

Technical Analysis

Implementation Approach

Technical Strategy: Pure filesystem reorganization and content extraction - no build process required. Create new directory structure for maintainer/contributor docs, split existing files, write new markdown overview files with consistent link formatting. Coordinate with Story #90 for CLI reference documentation.

Key Components:

  • Directory Structure: docs/customization/ (contributors), docs/performance/, docs/maintainers/
  • Content Extraction: Split docs/RELEASE.md (lines ~200-566 → release-process.md)
  • Link Creation: Consistent relative paths to .pair/adoption/tech/ and .pair/knowledge/guidelines/
  • README Cleanup: Trim apps/pair-cli/README.md to link to docs/cli/commands.md (created by Story KB Source Documentation & CLI Reference #90)

Data Flow:

docs/
├── getting-started/ (Story #90 reorganizes - no changes in this story)
├── cli/ (Story #90 creates - not touched by this story)
├── specs/ (Story #90 creates - not touched by this story)
├── customization/ (NEW - this story)
│   ├── README.md (index: "For contributors/maintainers extending pair")
│   └── extension-points.md (patterns → links to .pair/architecture/)
├── performance/ (NEW - this story)
│   ├── README.md (index)
│   ├── benchmark-report.md (existing, unchanged)
│   └── optimization.md (CLI + KB perf tips → links to .pair/adr/)
├── maintainers/ (NEW - this story)
│   ├── README.md (central index with all .pair/adoption/tech/ links)
│   └── release-process.md (extracted from RELEASE.md lines 200-566)
└── RELEASE.md (changelog only: version history, features, what's new)

Integration Points:

Technical Requirements

  • Markdown Compatibility: GitHub-flavored markdown with emoji support (📖 icon)
  • Link Format: Relative paths from docs/ subdirectories using ../../.pair/ pattern
  • No Build Process: Static markdown files, instant navigation
  • Validation: Manual link checking during PR review (could automate with markdown-link-check in future)
  • Documentation Standards: 2-3 paragraph overviews in docs/, full details in .pair/
  • Story Coordination: No modifications to docs/cli/, docs/specs/, or docs/getting-started/ (Story KB Source Documentation & CLI Reference #90 owns those)

Technical Risks and Mitigation

Risk Impact Probability Mitigation Strategy
Relative paths break after repo restructure Medium Low Use consistent ../../.pair/ format, test all links manually during PR review
Content duplication not fully removed Medium Medium Clear checklist of files to update, thorough PR review validation
.pair/ content missing or incomplete Medium Low Validate all link targets exist before creating links, create placeholders with TODO if needed
RELEASE.md split loses version context Low Low Keep all version history intact in RELEASE.md, only extract process instructions
Package README links to non-existent docs/cli/ Low Medium Coordinate with Story #90 - add link to docs/cli/commands.md created by #90
Overlap with Story #90 High Medium Clear boundary: #90 owns cli/specs/getting-started, #94 owns customization/performance/maintainers

Spike Requirements

Required Spikes: None - straightforward file reorganization with clear source content

Definition of Done Checklist

Development Completion

  • Directory structure created: docs/customization/, docs/performance/, docs/maintainers/
  • Customization section complete with 2 files (README, extension-points) and links to .pair/guidelines/
  • Performance section complete with 3 files (README, benchmark-report unchanged, optimization new) and links to .pair/adr/
  • Maintainers section complete with 2 files (README with central index, release-process extracted from RELEASE.md)
  • docs/RELEASE.md split complete: release process moved to maintainers/, changelog/version history remains
  • All links to .pair/ follow format: 📖 **Detailed documentation**: [Title](path)
  • All links validated: targets exist in .pair/ or placeholders created with TODO
  • Package READMEs cleaned up: @foomakers/pair-cli trimmed to quick start + link to docs/cli/commands.md
  • No modifications made to docs/cli/, docs/specs/, or docs/getting-started/ (Story KB Source Documentation & CLI Reference #90 territory)
  • Code review completed and approved
  • Documentation changes validate navigation paths work correctly

Quality Assurance

  • All 7 acceptance criteria tested and verified
  • Link validation: All .pair/ relative paths resolve correctly from docs/ subdirectories
  • Content duplication check: No duplicated content between docs/ and .pair/
  • RELEASE.md split verification: Process instructions completely moved, changelog intact
  • README cleanup verification: Technical guides removed, quick start preserved, docs/cli link added
  • Edge case testing: Broken link handling, missing content scenarios addressed
  • Navigation usability: Maintainers can navigate from docs/ to .pair/ smoothly
  • Story KB Source Documentation & CLI Reference #90 coordination: No conflicts with CLI/specs/getting-started documentation

Deployment and Release

  • Changes merged to main branch
  • Documentation structure visible in repository
  • No build/deployment required (static markdown files)
  • Post-merge verification: Browse docs/ structure on GitHub to confirm organization

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 points (reduced from 5 due to Story #90 handling CLI reference)
Confidence Level: High
Sizing Justification:

  • Directory creation and file moves: 0.5 pts
  • RELEASE.md split (extract lines 200-566): 1 pt
  • Customization section creation (2 files: README + extension points, no CLI API): 0.5 pt
  • Performance section (1 new optimization guide): 0.5 pt
  • Maintainers section (central index + release process): 0.5 pt
  • Package README cleanup (@foomakers/pair-cli + validation): 0.5 pt
  • Link validation and testing: 0.5 pt
  • Reduction reason: Story KB Source Documentation & CLI Reference #90 creates docs/cli/commands.md (CLI API reference), reducing scope of customization section

Sprint Capacity Validation

Sprint Fit Assessment: Yes - fits in single sprint
Development Time Estimate: 1.5-2 days
Testing Time Estimate: 0.5 day (link validation, navigation testing)
Total Effort Assessment: Fits within sprint capacity comfortably

Story Splitting Recommendations

Not Required - 3 points is appropriate for single sprint delivery. Splitting would fragment user experience (incomplete documentation reorganization provides no value).

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: None - all required .pair/ content already exists
Coordination Required:

Dependent Stories:

Shared Components:

Team Coordination

Development Roles Involved:

  • Product Engineer: File reorganization, content extraction, link creation
  • Product Manager: Review navigation logic, validate content organization
  • Maintainers: Validate release process extraction accuracy

External Dependencies

Third-party Integrations: None
Infrastructure Requirements: None
Compliance Requirements: None

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: Manual navigation testing, link validation, content verification
Test Data Requirements: Existing .pair/ content (architecture, ADRs, guidelines)
Environment Requirements: Local repository checkout, GitHub web interface for link testing

User Validation

User Feedback Collection: Internal team review of reorganized structure
Success Metrics:

  • All 7 acceptance criteria pass
  • Maintainers can navigate docs/ → .pair/ without confusion
  • No duplicate content between docs/ and .pair/
  • Package READMEs concise (<100 lines)
  • No conflicts with Story KB Source Documentation & CLI Reference #90 documentation

Rollback Plan: Git revert if structure doesn't improve navigation (low risk)

Notes and Additional Context

Refinement Session Insights:

  • CLI API reference moved to Story KB Source Documentation & CLI Reference #90 (docs/cli/commands.md) - this story focuses on contributor/maintainer docs only
  • RELEASE.md split clarified: lines 1-200 = changelog (stays), lines 200-566 = process (moves)
  • Link format standardized with emoji "📖" for visual marker
  • .pair/ established as source of truth, docs/ as navigation layer
  • Current documentation chaos (scattered/duplicated) makes this P0 priority
  • Clear boundary with Story KB Source Documentation & CLI Reference #90: no touching docs/cli/, docs/specs/, docs/getting-started/

Team Concerns: Coordination with Story #90 required - clear boundaries defined

Future Considerations:

Documentation Links:

Refinement Completed By: Product Manager (AI-assisted), Product Engineer
Refinement Date: December 17, 2025
Review and Approval: Confirmed

Task Breakdown

  • T-1: Create docs/ directory structure
  • T-2: Create Customization documentation section (contributor-focused)
  • T-3: Create Performance documentation section
  • T-4: Split RELEASE.md and create Maintainers section
  • T-5: Cleanup package READMEs
  • T-6: Validate documentation structure and links

T-1: Create docs/ directory structure

Priority: P0 | Estimated Hours: 0.5h | Bounded Context: Knowledge & Standards Context

Summary: Create directory structure for customization/, performance/, and maintainers/ sections in docs/ folder.

Type: Configuration

Description: Establish foundational directory structure to organize technical documentation into three main sections: Customization (contributor/architecture docs), Performance (benchmarks and optimization), and Maintainers (release process and technical decisions). This is the first step enabling all subsequent documentation organization tasks. Do NOT create docs/cli/ or docs/specs/ (Story #90 owns those).

Acceptance Criteria:

  • Primary deliverable: Three new directories created in docs/
  • Quality standard: Standard filesystem directory structure
  • Integration requirement: Directories ready to receive markdown files
  • Verification method: Verify directories exist with ls -la docs/

Technical Requirements:

  • Functionality: Create docs/customization/, docs/performance/, docs/maintainers/ directories
  • Performance: N/A (filesystem operation)
  • Security: N/A (documentation only)
  • Compatibility: Works across all operating systems (Linux, macOS, Windows)

Implementation Approach:

  • Technical Design: Simple directory creation using filesystem commands
  • Bounded Context & Modules: Knowledge & Standards Context - documentation organization
  • Files to Create:
    • docs/customization/ - Directory for contributor documentation
    • docs/performance/ - Directory for performance documentation
    • docs/maintainers/ - Directory for maintainer documentation
  • Technical Standards: N/A (filesystem operation)

Dependencies:

  • Technical: None
  • Tasks: None (foundation task)
  • Resources: Write access to repository

Implementation Steps:

  1. Create docs/customization/ directory
  2. Create docs/performance/ directory
  3. Create docs/maintainers/ directory
  4. Verify directories created successfully
  5. DO NOT create docs/cli/ or docs/specs/ (Story KB Source Documentation & CLI Reference #90 territory)

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing: Verify directories exist and are accessible

Notes: Foundation task - must complete before other documentation tasks can proceed. Story #90 creates docs/cli/ and docs/specs/ separately.

T-2: Create Customization documentation section (contributor-focused)

Priority: P0 | Estimated Hours: 1h | Bounded Context: Knowledge & Standards Context

Summary: Create customization documentation with README index and extension points guide for contributors, linking to authoritative .pair/ content.

Type: Documentation

Description: Build customization section documenting how contributors can extend pair CLI architecture. Create two files: README.md (section index for contributors/maintainers), extension-points.md (patterns for adding custom commands with architecture links). All documentation follows 2-3 paragraph overview pattern with "📖 Detailed documentation" links to .pair/knowledge/guidelines/. CLI API reference moved to Story #90 (docs/cli/commands.md).

Acceptance Criteria:

  • Primary deliverable: 2 markdown files in docs/customization/ with consistent link format
  • Quality standard: GitHub-flavored markdown, 2-3 paragraph overviews, links to .pair/ using standard format
  • Integration requirement: Links resolve to existing .pair/knowledge/guidelines/ content
  • Verification method: Manual review of content + link validation (AC1, AC2)

Technical Requirements:

  • Functionality: Document pair-cli extension architecture and patterns
  • Performance: N/A (static documentation)
  • Security: N/A (documentation only)
  • Compatibility: GitHub-flavored markdown with emoji support

Implementation Approach:

  • Technical Design: Create contributor-focused architecture overview with .pair/ links
  • Bounded Context & Modules: Knowledge & Standards Context - contributor documentation
  • Files to Create:
    • docs/customization/README.md - Section index explaining customization audience (contributors/maintainers)
    • docs/customization/extension-points.md - Extension patterns → links to .pair/knowledge/guidelines/architecture/
  • Technical Standards:
    • Link format: 📖 **Detailed documentation**: [Title](../../.pair/path/file.md)
    • Business rule: .pair/ is source of truth, docs/ provides navigation
    • No CLI API reference (moved to Story KB Source Documentation & CLI Reference #90 docs/cli/commands.md)

Dependencies:

  • Technical: Existing .pair/knowledge/guidelines/ content
  • Tasks: T-1 (directory structure must exist)
  • Resources: None

Implementation Steps:

  1. Create docs/customization/README.md with section overview (target: contributors)
  2. Create docs/customization/extension-points.md with pattern examples + architecture links
  3. Validate all .pair/ link targets exist
  4. Verify consistent link format across all files
  5. DO NOT create CLI API reference (Story KB Source Documentation & CLI Reference #90 handles in docs/cli/commands.md)

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing:
    • Click all .pair/ links to verify targets exist
    • Verify AC1: Architecture docs findable with proper links
    • Verify AC2: Extension points guide complete with examples

Notes: Focus on contributor/architecture docs only. User-facing CLI API reference is in Story #90 (docs/cli/commands.md). Keep overviews concise (2-3 paragraphs), detailed content stays in .pair/.

T-3: Create Performance documentation section

Priority: P0 | Estimated Hours: 1.5h | Bounded Context: Knowledge & Standards Context

Summary: Create performance documentation with README index and optimization guide, linking to ADRs. Keep existing benchmark-report.md unchanged.

Type: Documentation

Description: Build performance section with three components: README.md (section index), new optimization.md (CLI and KB performance tips with links to HTTP resume ADR and other performance specs in .pair/adr/), and preserve existing benchmark-report.md unchanged. Optimization guide covers caching strategies, KB download performance, link validation speed, and file processing tips.

Acceptance Criteria:

  • Primary deliverable: 2 new markdown files + 1 unchanged file in docs/performance/
  • Quality standard: Optimization guide contains actionable performance tips with ADR links
  • Integration requirement: Links to .pair/adoption/tech/adr/ ADRs (HTTP resume, streaming, etc.)
  • Verification method: Manual review + link validation (AC3)

Technical Requirements:

  • Functionality: Document CLI performance optimization strategies
  • Performance: N/A (static documentation)
  • Security: N/A (documentation only)
  • Compatibility: GitHub-flavored markdown

Implementation Approach:

  • Technical Design: Create optimization guide covering CLI startup, KB caching, download resume, file processing
  • Bounded Context & Modules: Knowledge & Standards Context - performance documentation
  • Files to Create/Modify:
    • docs/performance/README.md - Section index linking to benchmark and optimization
    • docs/performance/optimization.md - Performance tips → links to .pair/adoption/tech/adr/
    • docs/performance/benchmark-report.md - Keep unchanged
  • Technical Standards:
    • Link format: 📖 **Detailed documentation**: [ADR Title](../../.pair/adoption/tech/adr/file.md)
    • Edge case: If no performance ADRs exist, provide inline guidance without links

Dependencies:

  • Technical: Existing .pair/adoption/tech/adr/ ADRs (HTTP resume, checksum validation, streaming, TTY detection)
  • Tasks: T-1 (directory structure must exist)
  • Resources: docs/performance/benchmark-report.md (existing)

Implementation Steps:

  1. Create docs/performance/README.md as section index
  2. Identify relevant performance ADRs in .pair/adoption/tech/adr/
  3. Create docs/performance/optimization.md covering:
    • CLI performance (package size, startup time)
    • KB download caching and HTTP resume
    • Link validation speed
    • File processing optimization
  4. Add links to relevant ADRs (HTTP resume, streaming, etc.)
  5. Validate ADR link targets exist
  6. Verify benchmark-report.md remains unchanged

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing:
    • Click all ADR links to verify targets exist
    • Verify AC3: Optimization guide findable with caching strategy + ADR links
    • Verify benchmark-report.md unchanged

Notes: Check if performance ADRs exist in .pair/adr/ before creating links. If missing, provide inline guidance with TODO for future ADR creation.

T-4: Split RELEASE.md and create Maintainers section

Priority: P0 | Estimated Hours: 2h | Bounded Context: Knowledge & Standards Context

Summary: Extract release process from RELEASE.md (lines ~200-566) into maintainers/release-process.md, create maintainers/README.md with central index to all .pair/adoption/tech/ content, keep changelog in RELEASE.md.

Type: Documentation

Description: Split docs/RELEASE.md into two parts: keep version history/changelog/features in original file, move complete release process workflow (3-phase automation, prerequisites, manual dispatch, environment variables) to docs/maintainers/release-process.md. Create docs/maintainers/README.md as central navigation hub linking to all .pair/adoption/tech/ content (architecture, infrastructure, tech-stack, ux-ui, way-of-working, ADRs, bounded contexts).

Acceptance Criteria:

  • Primary deliverable: 2 new files in docs/maintainers/, modified docs/RELEASE.md with only changelog
  • Quality standard: Release process completely extracted, changelog intact, maintainers/README.md links to all tech adoption docs
  • Integration requirement: All .pair/adoption/tech/ links functional
  • Verification method: Manual review of split + link validation (AC4, AC5, AC6)

Technical Requirements:

  • Functionality: Separate changelog from process documentation, create central maintainer navigation
  • Performance: N/A (static documentation)
  • Security: N/A (documentation only)
  • Compatibility: GitHub-flavored markdown

Implementation Approach:

  • Technical Design: Extract lines ~200-566 from RELEASE.md, create comprehensive maintainer index
  • Bounded Context & Modules: Knowledge & Standards Context - maintainer documentation
  • Files to Create/Modify:
    • docs/maintainers/README.md - Central index with all .pair/adoption/tech/ links
    • docs/maintainers/release-process.md - Extracted release workflow (3-phase automation, prerequisites, etc.)
    • docs/RELEASE.md - Modified: remove process sections, keep only version history/changelog
  • Technical Standards:
    • Link format: 📖 **Detailed documentation**: [Title](../../.pair/adoption/tech/file.md)
    • RELEASE.md split rule: lines 1-~200 stay (changelog), lines ~200-566 move (process)

Dependencies:

  • Technical: Existing .pair/adoption/tech/ content (architecture, infrastructure, tech-stack, ux-ui, way-of-working, adr/, boundedcontext/)
  • Tasks: T-1 (directory structure must exist)
  • Resources: docs/RELEASE.md (source for split)

Implementation Steps:

  1. Create docs/maintainers/README.md with central index structure:
    • Release Management section → link to release-process.md
    • Technical Decisions section → links to architecture, infrastructure, tech-stack, way-of-working, ux-ui
    • ADRs section → link to .pair/adoption/tech/adr/README.md
    • Bounded Contexts section → link to .pair/adoption/tech/boundedcontext/README.md
  2. Extract release process content from docs/RELEASE.md (lines ~200-566)
  3. Create docs/maintainers/release-process.md with extracted content
  4. Modify docs/RELEASE.md: remove process sections, keep version history/features/changelog
  5. Validate all .pair/adoption/tech/ link targets exist
  6. Verify RELEASE.md changelog intact

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing:
    • Verify AC4: Release process findable in maintainers/release-process.md
    • Verify AC5: Maintainers/README.md contains all .pair/adoption/tech/ links
    • Verify AC6: RELEASE.md contains only changelog, no process instructions
    • Click all .pair/ links to verify targets exist

Notes: Carefully preserve version history in RELEASE.md. Release process is comprehensive (3-phase workflow, changeset integration, environment variables) - ensure complete extraction.

T-5: Cleanup package READMEs

Priority: P0 | Estimated Hours: 1h | Bounded Context: Knowledge & Standards Context

Summary: Trim @foomakers/pair-cli README and validate other package READMEs, removing long guides and adding docs/cli link (created by Story #90).

Type: Documentation

Description: Cleanup package READMEs to remove duplicated technical guides. For @foomakers/pair-cli README: keep quick feature list (bullets), installation methods (npm, pnpm, manual), quick start (1-2 commands); remove long usage guides, architecture details, troubleshooting; add link to docs/cli/commands.md (created by Story #90). Validate other package READMEs (content-ops, knowledge-hub, tools) follow same pattern.

Acceptance Criteria:

  • Primary deliverable: @foomakers/pair-cli README cleaned up (<100 lines), other package READMEs validated
  • Quality standard: Only project-specific quick start content, no duplicated guides, docs/cli link added
  • Integration requirement: CLI reference link points to docs/cli/commands.md (created by Story KB Source Documentation & CLI Reference #90)
  • Verification method: Manual review of README content (AC7)

Technical Requirements:

  • Functionality: Remove duplicated content, preserve essential quick start
  • Performance: N/A (static documentation)
  • Security: N/A (documentation only)
  • Compatibility: GitHub-flavored markdown

Implementation Approach:

  • Technical Design: Identify and remove long guides, preserve minimal quick start, add docs/cli link
  • Bounded Context & Modules: Knowledge & Standards Context - package documentation
  • Files to Modify:
    • apps/pair-cli/README.md - Major cleanup: remove usage guides, keep quick start + link to docs/cli/commands.md
    • packages/content-ops/README.md - Validation: check for duplication
    • packages/knowledge-hub/README.md - Validation: check for duplication
    • tools/*/README.md - Validation: check for duplication
  • Technical Standards:
    • README cleanup rule: quick start (1-2 commands) + features + installation + CLI reference link
    • CLI reference link format: 📚 **Full CLI reference**: [Commands](../../docs/cli/commands.md)

Dependencies:

Implementation Steps:

  1. Open apps/pair-cli/README.md
  2. Identify sections to remove:
  3. Keep sections:
    • Quick feature list (bullet points)
    • Installation methods (npm, pnpm, manual)
    • Quick start (1-2 example commands)
  4. Add CLI reference link: 📚 **Full CLI reference**: ../../docs/cli/commands.md
  5. Validate @foomakers/pair-cli README <100 lines
  6. Check other package READMEs for similar cleanup needs
  7. Apply consistent pattern across all package READMEs

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing:
    • Verify AC7: @foomakers/pair-cli README has quick start + docs/cli link, no long guides
    • Verify README <100 lines
    • Verify CLI reference link format consistent

Notes: Link points to docs/cli/commands.md created by Story #90. Major focus on @foomakers/pair-cli README - others likely already minimal. Coordinate with Story #90 to ensure docs/cli/commands.md exists before merging.

T-6: Validate documentation structure and links

Priority: P0 | Estimated Hours: 1h | Bounded Context: Knowledge & Standards Context

Summary: Comprehensive validation of all documentation changes: link targets exist, no duplication, navigation works, edge cases handled, no conflicts with Story #90.

Type: Testing

Description: Final validation ensuring all 7 acceptance criteria met. Verify: (1) all .pair/ links resolve correctly from docs/ subdirectories using ../../.pair/ pattern, (2) no content duplication between docs/ and .pair/, (3) RELEASE.md split correct (changelog stays, process moved), (4) READMEs cleaned up properly with docs/cli links, (5) edge cases handled (broken links → placeholders, missing specs → inline guidance), (6) navigation paths intuitive for maintainers, (7) no modifications to docs/cli/, docs/specs/, docs/getting-started/ (Story #90 territory).

Acceptance Criteria:

  • Primary deliverable: All documentation validated, issues documented or fixed
  • Quality standard: All 7 story acceptance criteria pass
  • Integration requirement: Complete navigation testing from GitHub web interface
  • Verification method: Checklist validation against Definition of Done

Technical Requirements:

  • Functionality: Validate all acceptance criteria and business rules
  • Performance: N/A (validation only)
  • Security: N/A (documentation only)
  • Compatibility: Test links work on GitHub web interface

Implementation Approach:

  • Technical Design: Systematic checklist-based validation across all documentation
  • Bounded Context & Modules: Knowledge & Standards Context - quality assurance
  • Files to Validate:
    • All docs/customization/ files
    • All docs/performance/ files
    • All docs/maintainers/ files
    • docs/RELEASE.md
    • All package READMEs
  • Technical Standards:
    • Link validation: All ../../.pair/ paths must resolve
    • No duplication: Content exists only in .pair/ or docs/, not both
    • Format compliance: All links follow 📖 **Detailed documentation**: [Title](path) standard
    • Story boundary: No changes to docs/cli/, docs/specs/, docs/getting-started/

Dependencies:

  • Technical: All .pair/ content exists, Story KB Source Documentation & CLI Reference #90 creates docs/cli/commands.md
  • Tasks: T-1, T-2, T-3, T-4, T-5 (all previous tasks must complete)
  • Resources: GitHub web interface for link testing

Implementation Steps:

  1. Link Validation:

    • Test all .pair/ links from docs/customization/ resolve correctly
    • Test all .pair/ links from docs/performance/ resolve correctly
    • Test all .pair/ links from docs/maintainers/ resolve correctly
    • Verify relative paths use ../../.pair/ pattern consistently

  2. Content Duplication Check:

    • Compare docs/ content against .pair/ content
    • Ensure no technical guides duplicated
    • Verify docs/ provides only overview + links

  3. Acceptance Criteria Validation:

    • AC1: Architecture docs in customization/README.md with .pair/ links ✓
    • AC2: Extension points in customization/extension-points.md with examples ✓
    • AC3: Performance optimization in performance/optimization.md with ADR links ✓
    • AC4: Release process in maintainers/release-process.md without changelog ✓
    • AC5: Maintainer index in maintainers/README.md with all .pair/adoption/tech/ links ✓
    • AC6: RELEASE.md contains only changelog, process moved ✓
    • AC7: Package READMEs cleaned up with docs/cli links ✓

  4. Story KB Source Documentation & CLI Reference #90 Coordination:

  5. Edge Case Verification:

    • Check handling of any broken .pair/ links (placeholders created?)
    • Verify missing ADRs handled (inline guidance provided?)

  6. Navigation Testing:

    • Navigate from docs/ → .pair/ via links (GitHub web interface)
    • Verify intuitive navigation for maintainers
    • Test breadcrumb understanding

  7. Final Checklist:

    • All DoD Development Completion items checked
    • All DoD Quality Assurance items checked
    • Document any issues or deviations

Testing Strategy:

  • Unit Tests: N/A
  • Integration Tests: N/A
  • Manual Testing:
    • Complete navigation testing on GitHub web interface
    • Verify all 7 acceptance criteria pass
    • Validate against complete Definition of Done checklist
    • Verify no conflicts with Story KB Source Documentation & CLI Reference #90 boundaries

Notes: Final quality gate before PR submission. Any validation failures should be fixed before marking story complete. Use GitHub web interface for link testing to ensure production behavior. Coordinate with Story #90 to ensure docs/cli/commands.md exists and is not modified by this story.

Task Breakdown Complete: 6 tasks covering all acceptance criteria, 1.5-2 day sprint capacity, Knowledge & Standards Context, coordinated with Story #90

Metadata

Metadata

Assignees

No one assigned

    Labels

    user storyWork item representing a user story

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions