diff --git a/.pair/knowledge/guidelines/collaboration/templates/branch-template.md b/.pair/knowledge/guidelines/collaboration/templates/branch-template.md index ac224ea9..f4975d36 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/branch-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/branch-template.md @@ -39,79 +39,16 @@ release/v1.2.0-preparation ## Branch Workflow -### 1. Branch Creation - -```bash -# Ensure you're on the latest base branch -git checkout main -git pull origin main - -# Create and switch to new branch -git checkout -b feature/US-123-user-authentication - -# Set upstream tracking -git push -u origin feature/US-123-user-authentication -``` - -### 2. Development Workflow - -```bash -# Make changes and stage them -git add . - -# Commit using commit template standards -git commit -m "feat(auth): implement user authentication system - -- Add JWT token generation and validation -- Implement password hashing with bcrypt -- Create authentication middleware -- Add login/logout endpoints - -Closes US-123" - -# Push changes regularly -git push origin feature/US-123-user-authentication -``` - -### 3. Branch Synchronization - -```bash -# Keep branch updated with base branch -git checkout main -git pull origin main -git checkout feature/US-123-user-authentication -git rebase main - -# Or use merge if preferred by team -git merge main - -# Push updated branch -git push origin feature/US-123-user-authentication --force-with-lease -``` - -### 4. Pull Request Creation - -```bash -# Ensure branch is ready for review -git push origin feature/US-123-user-authentication - -# Create PR using gh CLI or web interface -gh pr create --title "[US-123] feat: implement user authentication system" \ - --body-file .github/pull_request_template.md \ - --assignee @me \ - --reviewer @teammate1,@teammate2 -``` +1. **Creation**: branch from the up-to-date base branch, push with upstream tracking (`git checkout -b && git push -u origin `). +2. **Development**: commit per the [commit template](commit-template.md), push regularly. +3. **Synchronization**: keep the branch updated with the base branch (rebase or merge per team preference); after a rebase, push with `--force-with-lease`. +4. **Pull request**: create the PR per the [PR template](pr-template.md) when the branch is ready for review. ## Branch Lifecycle Management ### Branch States -- **Active Development** - Feature work in progress -- **Ready for Review** - Code complete, PR created -- **In Review** - Undergoing code review process -- **Approved** - Approved and ready to merge -- **Merged** - Successfully merged to base branch -- **Archived** - Branch deleted after merge +Active Development → Ready for Review → In Review → Approved → Merged → Archived (deleted). ### Branch Protection Rules @@ -123,18 +60,7 @@ gh pr create --title "[US-123] feat: implement user authentication system" \ ### Cleanup Process -```bash -# After successful merge, delete local branch -git checkout main -git pull origin main -git branch -d feature/US-123-user-authentication - -# Delete remote branch (usually done automatically after PR merge) -git push origin --delete feature/US-123-user-authentication - -# Clean up tracking references -git remote prune origin -``` +After merge: delete the local and remote branch, then `git remote prune origin` (remote deletion is usually automatic after PR merge). ## Branch Management Guidelines @@ -147,129 +73,26 @@ git remote prune origin ### Short-Lived Branches -- **feature/xxx** - Individual feature development -- **bug/xxx** - Bug fix development -- **chore/xxx** - Maintenance and tooling work +- **feature/xxx**, **bug/xxx**, **chore/xxx** - Individual story, fix, or maintenance work; created from the base branch, deleted after merge. ### Branching Strategy -#### Git Flow Model +- **Git Flow**: features branch from `develop`; `release/*` and `hotfix/*` branch toward `main`. +- **GitHub Flow**: everything branches directly from `main`. -```text -main -├── develop -│ ├── feature/US-123-authentication -│ ├── feature/US-124-user-profile -│ └── feature/US-125-dashboard -├── release/v1.2.0 -└── hotfix/v1.1.1-critical-fix -``` - -#### GitHub Flow Model - -```text -main -├── feature/US-123-authentication -├── feature/US-124-user-profile -└── hotfix/critical-security-fix -``` - -### Branch Naming Conventions - -#### User Story Branches - -```text -feature/US-[story-number]-[brief-description] -feature/US-123-user-authentication -feature/US-124-profile-management -``` - -#### Bug Fix Branches - -```text -bug/BUG-[bug-number]-[brief-description] -bug/BUG-456-login-validation -bug/BUG-789-payment-error -``` - -#### Task Branches - -```text -chore/TASK-[task-number]-[brief-description] -chore/TASK-321-update-dependencies -chore/TASK-654-refactor-api-client -``` - -#### Hotfix Branches - -```text -hotfix/[severity]-[brief-description] -hotfix/critical-payment-processing -hotfix/security-user-data-leak -``` +The adopted strategy determines each branch type's base branch. ## Commit Strategy on Branches -### Atomic Commits - -Each commit should represent a single logical change: - -```bash -git commit -m "feat(auth): add JWT token generation" -git commit -m "test(auth): add authentication middleware tests" -git commit -m "docs(auth): update API documentation for auth endpoints" -``` - -### Commit Message Format - -```text -(): - - - - -``` - -### Pre-Commit Checklist - -- [ ] Code compiles without errors -- [ ] All tests pass locally -- [ ] Code follows style guidelines -- [ ] Documentation updated if needed -- [ ] No sensitive data in commit -- [ ] Commit message follows standards +Commits on branches follow the [commit template](commit-template.md): atomic commits, standard message format, pre-commit checklist (tests pass, style clean, no sensitive data). ## Collaboration Guidelines -### Branch Ownership - - **Primary Developer** - Creates and owns the branch -- **Collaborators** - Can contribute with permission +- **Collaborators** - Can contribute with permission (pull, commit, push on the shared branch) - **Reviewers** - Review code but don't commit directly -### Collaboration Commands - -```bash -# Add collaborator to branch -git checkout feature/US-123-authentication -git pull origin feature/US-123-authentication - -# Make changes and push -git add . -git commit -m "feat(auth): add additional validation" -git push origin feature/US-123-authentication -``` - -### Conflict Resolution - -```bash -# When conflicts occur during rebase/merge -git status # Check conflicted files -# Edit files to resolve conflicts -git add . -git rebase --continue # or git merge --continue -git push origin feature/US-123-authentication --force-with-lease -``` +Conflicts are resolved by the branch owner during rebase/merge, then pushed with `--force-with-lease`. ## Quality Assurance @@ -283,127 +106,11 @@ git push origin feature/US-123-authentication --force-with-lease - [ ] No merge commits in feature branch - [ ] Branch is up to date with base branch -### Automated Checks - -- **CI/CD Pipeline** - Runs on every push -- **Code Quality** - Linting and formatting checks -- **Security Scan** - Dependency and code security -- **Test Coverage** - Maintains minimum coverage threshold - -### Manual Review Points - -- **Code Standards** - Follows team conventions -- **Architecture** - Aligns with system design -- **Performance** - No performance regressions -- **Security** - No security vulnerabilities +Automated checks (CI/CD, linting, security scan, coverage) and review standards are defined in the [quality-assurance guidelines](../../quality-assurance/README.md). ## Troubleshooting -### Common Issues - -#### Branch Diverged from Base - -```bash -# Solution: Rebase onto latest base -git checkout main -git pull origin main -git checkout feature/US-123-authentication -git rebase main -``` - -#### Force Push After Rebase - -```bash -# Use force-with-lease for safety -git push origin feature/US-123-authentication --force-with-lease -``` - -#### Branch Name Conflicts - -```bash -# Rename local branch -git branch -m old-branch-name new-branch-name - -# Delete old remote branch and push new one -git push origin --delete old-branch-name -git push -u origin new-branch-name -``` - -#### Lost Commits After Rebase - -```bash -# Use reflog to find lost commits -git reflog -git checkout [commit-hash] -git checkout -b recovery-branch -``` - -### Emergency Procedures - -#### Revert Branch Changes - -```bash -# Revert last commit -git revert HEAD - -# Revert multiple commits -git revert HEAD~3..HEAD - -# Hard reset to specific commit (use with caution) -git reset --hard [commit-hash] -``` - -#### Emergency Hotfix Process - -```bash -# Create hotfix branch from main -git checkout main -git pull origin main -git checkout -b hotfix/critical-security-fix - -# Make minimal fix -# Test thoroughly -# Create emergency PR with expedited review -``` - ---- - -## Branch Templates for Different Types - -### Feature Branch Template - -```text -Branch: feature/US-[ID]-[description] -Purpose: Implement new functionality -Base: develop (or main for GitHub Flow) -Lifecycle: Create → Develop → PR → Review → Merge → Delete -``` - -### Bug Fix Branch Template - -```text -Branch: bug/BUG-[ID]-[description] -Purpose: Fix identified issues -Base: develop (or main for hotfixes) -Lifecycle: Create → Fix → Test → PR → Review → Merge → Delete -``` - -### Chore Branch Template - -```text -Branch: chore/TASK-[ID]-[description] -Purpose: Maintenance, refactoring, tooling -Base: develop (or main) -Lifecycle: Create → Work → PR → Review → Merge → Delete -``` - -### Release Branch Template - -```text -Branch: release/v[version] -Purpose: Release preparation and stabilization -Base: develop -Lifecycle: Create → Stabilize → Merge to main → Tag → Delete -``` - -This branch template provides comprehensive guidance for professional Git workflow management, ensuring consistent practices across all development activities. +- **Branch diverged from base**: rebase onto the latest base branch. +- **Push rejected after rebase**: `git push --force-with-lease`. +- **Lost commits after rebase**: recover via `git reflog`. +- **Emergency hotfix**: branch `hotfix/-` from `main`, minimal fix, expedited PR review. diff --git a/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md b/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md index 18aedf0a..7cacec41 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md @@ -190,11 +190,7 @@ Performance Tests: ✅ Within Limits / ⚠️ Degradation Detected ### Code Improvements ```diff -// Current implementation -- if (user != null && user.isActive() == true) { -+ if (user?.isActive()) { - // Process user -} +[Suggested code change in diff format] ``` ### Architecture Suggestions @@ -281,112 +277,4 @@ Performance Tests: ✅ Within Limits / ⚠️ Degradation Detected --- -## Review Templates for Different Types - -### Feature Review Template - -```markdown -## Feature Review: [Feature Name] - -**User Story:** [US-XXX] -**Business Value:** [Expected value delivery] - -### Functionality Validation - -- [ ] Feature matches acceptance criteria -- [ ] User experience is intuitive -- [ ] Edge cases handled appropriately - -### Implementation Quality - -- [ ] Code is clean and maintainable -- [ ] Architecture aligns with system design -- [ ] Performance meets requirements -``` - -### Bug Fix Review Template - -```markdown -## Bug Fix Review: [Bug Description] - -**Bug ID:** [BUG-XXX] -**Severity:** [Critical/High/Medium/Low] -**Root Cause:** [Identified cause] - -### Fix Validation - -- [ ] Root cause properly addressed -- [ ] Fix doesn't introduce new issues -- [ ] Regression test added - -### Quality Assurance - -- [ ] Minimal changes made -- [ ] All related scenarios tested -- [ ] Documentation updated if needed -``` - -### Refactoring Review Template - -```markdown -## Refactoring Review: [Code Area] - -**Objective:** [Refactoring goal] -**Scope:** [What's being refactored] - -### Refactoring Quality - -- [ ] Code readability improved -- [ ] Performance maintained or improved -- [ ] Functionality unchanged -- [ ] Test coverage maintained - -### Risk Assessment - -- [ ] No breaking changes introduced -- [ ] Backward compatibility maintained -- [ ] Deployment risk minimized -``` - -### Hotfix Review Template - -```markdown -## HOTFIX Review: [Critical Issue] - -**Severity:** CRITICAL -**Issue:** [Production problem] -**Impact:** [Business/user impact] - -### Emergency Review Focus - -- [ ] Fix addresses immediate problem -- [ ] Minimal change approach used -- [ ] Risk of new issues minimized -- [ ] Rollback plan ready - -### Expedited Process - -- [ ] Priority reviewer assigned -- [ ] Fast-track approval process -- [ ] Emergency deployment prepared -``` - -## Review Quality Standards - -### Effective Review Practices - -1. **Be Constructive** - Focus on code, not the person -2. **Be Specific** - Provide clear, actionable feedback -3. **Be Timely** - Complete reviews within agreed timeframes -4. **Be Thorough** - Cover all aspects systematically -5. **Be Educational** - Share knowledge and best practices - -### Review Communication Guidelines - -- **Use positive language** - Frame feedback constructively -- **Explain the why** - Provide reasoning for suggestions -- **Offer solutions** - Don't just identify problems -- **Ask questions** - Seek understanding before criticizing -- **Acknowledge good work** - Recognize quality implementations - -This code review template ensures thorough, consistent, and constructive code reviews that maintain high code quality standards while supporting team learning and collaboration. +For review type emphasis: Feature → acceptance criteria and UX; Bug Fix → root cause addressed + regression test; Refactoring → behavior unchanged, coverage maintained; Hotfix → minimal change, rollback ready. Review conduct standards: see [team standards](../team/standards.md) (single source of truth). diff --git a/.pair/knowledge/guidelines/collaboration/templates/commit-template.md b/.pair/knowledge/guidelines/collaboration/templates/commit-template.md index 787e0535..a06e10e2 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/commit-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/commit-template.md @@ -65,9 +65,7 @@ Refs: #T-456 Refs: #T-456 ``` -## Commit Message Examples - -### Feature Implementation +## Commit Message Example ```text [US-789] feat: add real-time notifications system @@ -76,72 +74,13 @@ Implement WebSocket-based notification delivery: - Add WebSocket server configuration - Create notification event handlers - Implement client-side notification display -- Add notification persistence to database -This enables users to receive instant updates without page refresh, -improving user engagement and system responsiveness. +This enables users to receive instant updates without page refresh. Refs: #T-234, #T-235 ``` -### Bug Fix - -```text -[US-456] fix: resolve memory leak in data processing - -- Fix unclosed database connections in batch processor -- Add proper cleanup in error handling paths -- Implement connection pooling timeout -- Add memory usage monitoring - -The memory leak was causing application crashes during large -data imports. This fix ensures proper resource cleanup and -adds monitoring to prevent future issues. - -Closes #BUG-123 -``` - -### Refactoring - -```text -[US-321] refactor: restructure user management module - -- Extract user validation into separate service -- Simplify user creation workflow -- Improve error handling consistency -- Add comprehensive unit test coverage - -No functional changes - purely code organization improvement -for better maintainability and testability. - -Refs: #T-567 -``` - -### Documentation - -```text -[US-654] docs: add API documentation for user endpoints - -- Document authentication endpoints -- Add request/response examples -- Include error code explanations -- Add usage examples for common scenarios - -Refs: #T-890 -``` - -### Configuration/Setup - -```text -[US-987] chore: configure production deployment pipeline - -- Add Docker configuration for production -- Set up environment variable management -- Configure health check endpoints -- Add logging and monitoring setup - -Refs: #T-111 -``` +The same structure applies to every type (fix, refactor, docs, chore, ...): subject line, optional body with bullets explaining what and why, optional footer with references. ## Commit Message Guidelines @@ -189,46 +128,7 @@ Format: [BUG-###] - Bug tracking number Example: Closes #BUG-123 ``` -## Non-Code Task Commits - -### Documentation Tasks - -```text -[US-456] docs: update user onboarding guide - -- Add screenshots for new UI elements -- Update step-by-step instructions -- Include troubleshooting section -- Add FAQ for common issues - -Refs: #T-789 -``` - -### Configuration Changes - -```text -[US-123] chore: update project configuration - -- Configure ESLint rules for TypeScript -- Add Prettier formatting configuration -- Update package.json scripts -- Add VS Code workspace settings - -Refs: #T-234 -``` - -### Infrastructure Setup - -```text -[US-789] build: setup CI/CD pipeline - -- Add GitHub Actions workflow configuration -- Configure automated testing on pull requests -- Set up deployment to staging environment -- Add code quality checks - -Refs: #T-345 -``` +Non-code tasks (documentation, configuration, infrastructure) follow the same format with the matching type (`docs`, `chore`, `build`, `ci`). ## Quality Checklist @@ -257,39 +157,12 @@ Before committing, ensure: ## Atomic Commit Principles -### Single Responsibility - -Each commit should represent one logical change: - -- ✅ Good: Fix one specific bug -- ❌ Bad: Fix bug + add new feature + update documentation - -### Complete Functionality - -Commits should leave the codebase in a working state: - -- ✅ Good: Complete feature implementation with tests -- ❌ Bad: Partial implementation that breaks build - -### Meaningful Scope - -Commit scope should be appropriately sized: - -- ✅ Good: Implement one component or fix one issue -- ❌ Bad: Massive commit touching unrelated areas +- **Single responsibility**: one logical change per commit (not bug fix + feature + docs together) +- **Complete functionality**: each commit leaves the codebase in a working state +- **Meaningful scope**: one component or one issue — never a massive commit touching unrelated areas ## Branch and Merge Strategy -### Feature Branch Commits - -```text -# During feature development -[US-123] test: add failing tests for user search -[US-123] feat: implement basic search functionality -[US-123] refactor: optimize search performance -[US-123] docs: document search API endpoints -``` - ### Squash Merge Strategy When using squash merge, final commit should summarize the feature: @@ -309,72 +182,12 @@ Closes #T-234, #T-235, #T-236 ### Merge Commit Strategy -When preserving commit history, ensure each commit follows guidelines: - -```text -# Each commit in the branch should be clean and follow standards -[US-123] test: add unit tests for search service -[US-123] feat: implement search backend API -[US-123] feat: create search UI components -[US-123] refactor: optimize search query performance -``` +When preserving commit history, each commit in the branch must be clean and follow the standards above. --- ## Common Anti-Patterns to Avoid -### Poor Commit Messages - -❌ **Bad Examples:** - -```text -fix stuff -WIP -asdf -update code -fix bug -``` - -✅ **Good Examples:** - -```text -[US-123] fix: resolve null pointer in user validation -[US-456] feat: add email notification service -[US-789] refactor: extract common validation logic -``` - -### Inappropriate Grouping - -❌ **Bad:** Mixed unrelated changes - -```text -[US-123] feat: add user search + fix login bug + update docs -``` - -✅ **Good:** Separate logical commits - -```text -[US-123] feat: add user search functionality -[US-124] fix: resolve login validation error -[US-123] docs: update search API documentation -``` - -### Missing Context - -❌ **Bad:** No explanation for complex changes - -```text -[US-123] refactor: change user service -``` - -✅ **Good:** Clear explanation of reasoning - -```text -[US-123] refactor: extract user validation to separate service - -- Move validation logic from controller to dedicated service -- Improve testability and code reuse -- Prepare for upcoming role-based permissions feature - -Refs: #T-456 -``` +❌ Vague messages (`fix stuff`, `WIP`, `update code`) — ✅ `[US-123] fix: resolve null pointer in user validation` +❌ Mixed unrelated changes in one commit — ✅ separate logical commits per story/type +❌ Complex change with no body — ✅ body explaining what and why, with refs diff --git a/.pair/knowledge/guidelines/collaboration/templates/epic-template.md b/.pair/knowledge/guidelines/collaboration/templates/epic-template.md index 3fc1183b..8e6a8fee 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/epic-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/epic-template.md @@ -31,17 +31,11 @@ ### Success Metrics (KPIs) -- **Business Metric 1:** [Metric name] - Target: [target value] +- **Business Metric N:** [Metric name] - Target: [target value] - **Measurement method:** [How this will be tracked] - **Current baseline:** [Current performance level] -- **Business Metric 2:** [Metric name] - Target: [target value] - - **Measurement method:** [Tracking approach] - - **Current baseline:** [Starting point] - -- **Business Metric 3:** [Metric name] - Target: [target value] - - **Measurement method:** [Measurement strategy] - - **Current baseline:** [Current state] +[Repeat per metric] ### Return on Investment (ROI) @@ -69,31 +63,24 @@ ### Pain Points Addressed -1. **Pain Point 1:** [Specific customer or business problem] +1. **Pain Point N:** [Specific customer or business problem] - **Impact:** [Cost, frustration, or inefficiency caused] - **Frequency:** [How often this problem occurs] -2. **Pain Point 2:** [Another critical issue] - - **Impact:** [Business or user impact] - - **Frequency:** [Occurrence rate] +[Repeat per pain point] ## Target Users & Personas ### Primary Users -**Persona 1:** [Primary user type] +**Persona N:** [User type] - **Demographics:** [Age, role, experience level] - **Goals:** [What they want to achieve] - **Frustrations:** [Current challenges they face] - **Usage Patterns:** [How they interact with the system] -**Persona 2:** [Secondary user type] - -- **Demographics:** [Relevant characteristics] -- **Goals:** [Their objectives] -- **Frustrations:** [Pain points] -- **Usage Patterns:** [Interaction preferences] +[Repeat per persona] ### User Journey @@ -107,17 +94,11 @@ ### Key Capabilities -1. **Capability 1:** [Major functionality or feature area] +1. **Capability N:** [Major functionality or feature area] - **Description:** [What this capability provides] - **Value:** [Why this is important for users] -2. **Capability 2:** [Another core capability] - - **Description:** [Functionality description] - - **Value:** [User and business value] - -3. **Capability 3:** [Additional key capability] - - **Description:** [What it enables] - - **Value:** [Impact and importance] +[Repeat per capability] ### Solution Differentiators @@ -129,14 +110,11 @@ ### Themes & Feature Areas -1. **Theme 1:** [Logical grouping of related features] - - [Feature/Story area 1.1] - - [Feature/Story area 1.2] - - [Feature/Story area 1.3] +1. **Theme N:** [Logical grouping of related features] + - [Feature/Story area N.1] + - [Feature/Story area N.2] -2. **Theme 2:** [Another feature grouping] - - [Feature/Story area 2.1] - - [Feature/Story area 2.2] +[Repeat per theme] ### User Stories (High-Level) @@ -146,9 +124,7 @@ - **Story points:** [Estimate] - **Dependencies:** [Key dependencies] -- [ ] **US-XXX:** As a [user] I want [capability] so that [benefit] - - **Story points:** [Estimate] - - **Dependencies:** [Dependencies] +[Repeat per story] #### Should-Have Stories (P1) @@ -187,8 +163,7 @@ | Risk | Impact | Probability | Mitigation Strategy | | ------------------ | --------------- | --------------- | ------------------------- | -| [Technical risk 1] | High/Medium/Low | High/Medium/Low | [Technical mitigation] | -| [Technical risk 2] | High/Medium/Low | High/Medium/Low | [Risk reduction approach] | +| [Technical risk] | High/Medium/Low | High/Medium/Low | [Technical mitigation] | ### Infrastructure & Tooling @@ -244,15 +219,12 @@ ### Critical Path Dependencies -- [ ] **Dependency 1:** [Critical external dependency] +- [ ] **Dependency N:** [Critical external dependency] - **Owner:** [Responsible team/person] - **Required by:** [Date] - **Risk level:** [High/Medium/Low] -- [ ] **Dependency 2:** [Another critical dependency] - - **Owner:** [Responsible party] - - **Required by:** [Deadline] - - **Risk level:** [Risk assessment] +[Repeat per dependency] ### Release Strategy @@ -267,22 +239,19 @@ | Risk | Impact | Probability | Mitigation Strategy | Owner | | ----------------- | --------------- | --------------- | --------------------- | -------- | -| [Business risk 1] | High/Medium/Low | High/Medium/Low | [Business mitigation] | [Person] | -| [Market risk] | High/Medium/Low | High/Medium/Low | [Market strategy] | [Person] | +| [Business risk] | High/Medium/Low | High/Medium/Low | [Business mitigation] | [Person] | ### Technical Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | | ------------------ | --------------- | --------------- | ---------------------- | -------- | -| [Technical risk 1] | High/Medium/Low | High/Medium/Low | [Technical solution] | [Person] | -| [Integration risk] | High/Medium/Low | High/Medium/Low | [Integration approach] | [Person] | +| [Technical risk] | High/Medium/Low | High/Medium/Low | [Technical solution] | [Person] | ### Resource Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | | --------------------- | --------------- | --------------- | ---------------------- | -------- | -| [Resource constraint] | High/Medium/Low | High/Medium/Low | [Resource plan] | [Person] | -| [Skill gap] | High/Medium/Low | High/Medium/Low | [Training/hiring plan] | [Person] | +| [Resource risk] | High/Medium/Low | High/Medium/Low | [Resource plan] | [Person] | ## Success Validation diff --git a/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md b/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md index b7b5004f..85627334 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md @@ -48,22 +48,13 @@ ### Primary Business Goals -1. **Objective 1:** [Specific, measurable business objective] +1. **Objective N:** [Specific, measurable business objective] - **Target:** [Quantified target with timeline] - **Baseline:** [Current performance level] - **Impact:** [Expected business impact] -2. **Objective 2:** [Another key business objective] - - - **Target:** [Measurable target] - - **Baseline:** [Starting point] - - **Impact:** [Business value] - -3. **Objective 3:** [Additional strategic objective] - - **Target:** [Specific target] - - **Baseline:** [Current state] - - **Impact:** [Expected outcome] +[Repeat per objective] ### Success Metrics & KPIs @@ -85,19 +76,14 @@ ### Customer Segments -**Primary Segment:** [Primary customer segment] +**[Primary | Secondary] Segment:** [Customer segment] - **Size:** [Market size and addressable population] - **Characteristics:** [Key demographic and behavioral traits] - **Current Pain Points:** [Major challenges and frustrations] - **Value Proposition:** [How initiative addresses their needs] -**Secondary Segment:** [Secondary customer segment] - -- **Size:** [Segment size] -- **Characteristics:** [Relevant traits] -- **Current Pain Points:** [Challenges] -- **Value Proposition:** [Value delivered] +[Repeat per segment] ### Customer Journey Impact @@ -117,16 +103,13 @@ ### Key Solution Components -1. **Component 1:** [Major solution area or capability] +1. **Component N:** [Major solution area or capability] - **Description:** [What this component delivers] - **Value:** [Business and customer value] - **Timeline:** [Development timeframe] -2. **Component 2:** [Another key solution component] - - **Description:** [Component description] - - **Value:** [Value proposition] - - **Timeline:** [Delivery timeline] +[Repeat per component] ### Innovation & Differentiation @@ -147,11 +130,7 @@ - **Timeline:** [Expected delivery window] - **Dependencies:** [Key dependencies] -- [ ] **EP-XXX:** [Another critical epic] - - **Business Value:** [Value delivered] - - **Epic Points:** [Size estimate] - - **Timeline:** [Delivery timeframe] - - **Dependencies:** [Dependencies] +[Repeat per epic — same fields for each priority tier below] #### Medium-Priority Epics (Should-Have) @@ -251,24 +230,19 @@ | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | ------------------ | ------------ | ------------ | ---------------------- | -------- | -------- | -| [Market risk] | High/Med/Low | High/Med/Low | [Market mitigation] | [Person] | [When] | -| [Competitive risk] | High/Med/Low | High/Med/Low | [Competitive strategy] | [Person] | [When] | -| [Technology risk] | High/Med/Low | High/Med/Low | [Tech mitigation] | [Person] | [When] | +| [Strategic risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ### Execution Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | --------------- | ------------ | ------------ | --------------------- | -------- | -------- | -| [Resource risk] | High/Med/Low | High/Med/Low | [Resource plan] | [Person] | [When] | -| [Timeline risk] | High/Med/Low | High/Med/Low | [Schedule mitigation] | [Person] | [When] | -| [Quality risk] | High/Med/Low | High/Med/Low | [Quality assurance] | [Person] | [When] | +| [Execution risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ### Financial Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | ---------------- | ------------ | ------------ | -------------------- | -------- | -------- | -| [Budget overrun] | High/Med/Low | High/Med/Low | [Budget controls] | [Person] | [When] | -| [ROI shortfall] | High/Med/Low | High/Med/Low | [Value optimization] | [Person] | [When] | +| [Financial risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ## Go-to-Market Strategy @@ -338,23 +312,11 @@ ### Communication Plan -#### Executive Updates: - -- **Frequency:** [How often executive updates occur] -- **Format:** [Update format and content] -- **Audience:** [Who receives executive updates] - -#### Team Communication: - -- **Frequency:** [Team communication rhythm] -- **Format:** [Team update format] -- **Audience:** [Extended team and stakeholders] - -#### Organization Communication: - -- **Frequency:** [Company-wide communication schedule] -- **Format:** [Organizational update approach] -- **Audience:** [Broader organization] +| Level | Frequency | Format | Audience | +| ------------------ | ----------- | -------- | ---------- | +| **Executive** | [How often] | [Format] | [Who] | +| **Team** | [Rhythm] | [Format] | [Who] | +| **Organization** | [Schedule] | [Format] | [Who] | ### Decision-Making Framework diff --git a/.pair/knowledge/guidelines/collaboration/templates/pr-template.md b/.pair/knowledge/guidelines/collaboration/templates/pr-template.md index 9871dd25..82664511 100644 --- a/.pair/knowledge/guidelines/collaboration/templates/pr-template.md +++ b/.pair/knowledge/guidelines/collaboration/templates/pr-template.md @@ -248,12 +248,7 @@ Impact: [Improvement/degradation percentage] ### Testing the Changes ```bash -# Steps to test this PR locally -git checkout [branch-name] -npm install # or relevant dependency installation -npm run test # run test suite -npm run start # start local development -# Navigate to [specific URLs] to test functionality +[Commands to test this PR locally: checkout, install, test, run] ``` ### Key Test Scenarios @@ -299,126 +294,7 @@ npm run start # start local development --- -## Templates for Different PR Types - -### Feature PR Template - -```markdown -## Feature Implementation: [Feature Name] - -**User Story:** [US-XXX] -**Epic:** [EP-XXX] - -### What's New - -[Description of new functionality added] - -### User Impact - -[How this improves user experience] - -### Technical Implementation - -[Key technical decisions and approaches] -``` - -### Bug Fix PR Template - -```markdown -## Bug Fix: [Issue Description] - -**Bug Report:** [BUG-XXX] -**Severity:** [Critical/High/Medium/Low] - -### Problem - -[Description of the bug and its impact] - -### Root Cause - -[Explanation of what caused the issue] - -### Solution - -[How the fix addresses the root cause] - -### Verification - -[How the fix was tested and verified] -``` - -### Refactoring PR Template - -```markdown -## Refactoring: [Code Area] - -**Story:** [US-XXX] -**Type:** Code Quality Improvement - -### Motivation - -[Why this refactoring was needed] - -### Changes Made - -[What was restructured or improved] - -### Benefits - -[Improved maintainability, performance, or readability] - -### Risk Assessment - -[Low risk - no functional changes] -``` - -### Documentation PR Template - -```markdown -## Documentation Update: [Documentation Area] - -**Story:** [US-XXX] -**Type:** Documentation - -### Documentation Changes - -[What documentation was added or updated] - -### Target Audience - -[Who will benefit from this documentation] - -### Coverage - -[What areas are now better documented] -``` - -### Hotfix PR Template - -```markdown -## HOTFIX: [Critical Issue] - -**Severity:** CRITICAL -**Issue:** [Production issue description] - -### Immediate Problem - -[What is broken in production] - -### Quick Fix - -[Minimal change to resolve immediate issue] - -### Full Solution Plan - -[Link to planned comprehensive fix] - -### Rollback Plan - -[How to quickly rollback if needed] -``` - ---- +Type emphasis: Feature → user impact + technical decisions; Bug Fix → problem, root cause, solution, verification; Refactoring → motivation + no functional changes; Documentation → audience + coverage; Hotfix → immediate problem, minimal fix, rollback plan. ## Pre-Submission Checklist diff --git a/.pair/knowledge/guidelines/user-experience/markdown-templates.md b/.pair/knowledge/guidelines/user-experience/markdown-templates.md index 555c5492..4e59c3da 100644 --- a/.pair/knowledge/guidelines/user-experience/markdown-templates.md +++ b/.pair/knowledge/guidelines/user-experience/markdown-templates.md @@ -2,30 +2,11 @@ ## Introduction -Markdown templates provide standardized formats for documentation, content creation, and communication across design and development workflows. These templates ensure consistency, improve efficiency, and maintain quality standards while facilitating collaboration between team members and stakeholders. +Markdown templates provide standardized formats for documentation, content creation, and communication across design and development workflows. ## Scope -### In Scope - -- Documentation template creation and maintenance -- Content structure standardization -- Design system documentation templates -- User story and requirement templates -- Process documentation frameworks -- Meeting notes and decision record templates -- Design review and handoff templates -- Quality assurance and testing templates -- Project communication templates -- Knowledge base article templates - -### Out of Scope - -- Content writing training -- Markdown syntax education -- Platform-specific implementation -- Content strategy development -- Editorial workflow management +**In scope**: documentation, design system, process, UX research, and project management templates. **Out of scope**: content writing training, markdown syntax education, platform-specific implementation, content strategy. ## Template Categories @@ -411,128 +392,10 @@ Description of process experiment to try. ## Content Standards -### Writing Guidelines - -#### Voice and Tone - -- Clear and concise language -- Active voice preference -- Professional yet approachable tone -- Consistent terminology usage -- Inclusive language practices - -#### Structure Principles - -- Logical information hierarchy -- Scannable content organization -- Consistent heading levels -- Bullet points for lists -- Tables for structured data - -#### Formatting Standards - -- Consistent heading styles -- Proper link formatting -- Code block usage -- Image alt text inclusion -- Table header definitions - -### Template Maintenance - -#### Version Control - -- Template versioning system -- Change tracking and history -- Update notification process -- Approval workflow for changes -- Archive management - -#### Quality Assurance - -- Regular template review -- Usage analytics monitoring -- Feedback collection -- Improvement identification -- Update implementation - -## Implementation Guidelines - -### Tool Integration - -#### Platform Compatibility - -- GitHub markdown compatibility -- Notion integration support -- Confluence adaptation -- Slack formatting consideration -- Email template variations - -#### Automation Opportunities - -- Template generation scripts -- Content validation tools -- Formatting automation -- Link checking systems -- Version update notifications - -### Team Adoption - -#### Training and Onboarding - -- Template usage training -- Best practice guidelines -- Example implementations -- Common mistake prevention -- Feedback collection methods - -#### Compliance Monitoring - -- Template usage tracking -- Quality standard enforcement -- Consistency checking -- Improvement suggestions -- Support provision - -## Best Practices - -### Content Creation - -- Start with template selection -- Follow established patterns -- Maintain consistency -- Include required sections -- Review before publishing - -### Template Evolution - -- Regular usage analysis -- Feedback integration -- Continuous improvement -- Version management -- Change communication - -### Team Collaboration - -- Shared template library -- Collaborative editing -- Review processes -- Knowledge sharing -- Standard adoption - -## Measurement and Analytics - -### Usage Metrics - -- Template adoption rates -- Content creation efficiency -- Quality improvement indicators -- Team satisfaction scores -- Process compliance rates +- **Voice and tone**: clear, concise, active voice, consistent and inclusive terminology. +- **Structure**: logical hierarchy, scannable organization, consistent heading levels, bullets for lists, tables for structured data. +- **Formatting**: proper link formatting, code blocks for code, image alt text, table headers. -### Continuous Improvement +## Template Maintenance -- Regular template audits -- User feedback integration -- Process optimization -- Tool integration enhancement -- Training effectiveness measurement +Templates are versioned with the knowledge base: propose changes via PR, review regularly, evolve from usage feedback. When creating content, start from the matching template, include its required sections, and review before publishing. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/branch-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/branch-template.md index ac224ea9..f4975d36 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/branch-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/branch-template.md @@ -39,79 +39,16 @@ release/v1.2.0-preparation ## Branch Workflow -### 1. Branch Creation - -```bash -# Ensure you're on the latest base branch -git checkout main -git pull origin main - -# Create and switch to new branch -git checkout -b feature/US-123-user-authentication - -# Set upstream tracking -git push -u origin feature/US-123-user-authentication -``` - -### 2. Development Workflow - -```bash -# Make changes and stage them -git add . - -# Commit using commit template standards -git commit -m "feat(auth): implement user authentication system - -- Add JWT token generation and validation -- Implement password hashing with bcrypt -- Create authentication middleware -- Add login/logout endpoints - -Closes US-123" - -# Push changes regularly -git push origin feature/US-123-user-authentication -``` - -### 3. Branch Synchronization - -```bash -# Keep branch updated with base branch -git checkout main -git pull origin main -git checkout feature/US-123-user-authentication -git rebase main - -# Or use merge if preferred by team -git merge main - -# Push updated branch -git push origin feature/US-123-user-authentication --force-with-lease -``` - -### 4. Pull Request Creation - -```bash -# Ensure branch is ready for review -git push origin feature/US-123-user-authentication - -# Create PR using gh CLI or web interface -gh pr create --title "[US-123] feat: implement user authentication system" \ - --body-file .github/pull_request_template.md \ - --assignee @me \ - --reviewer @teammate1,@teammate2 -``` +1. **Creation**: branch from the up-to-date base branch, push with upstream tracking (`git checkout -b && git push -u origin `). +2. **Development**: commit per the [commit template](commit-template.md), push regularly. +3. **Synchronization**: keep the branch updated with the base branch (rebase or merge per team preference); after a rebase, push with `--force-with-lease`. +4. **Pull request**: create the PR per the [PR template](pr-template.md) when the branch is ready for review. ## Branch Lifecycle Management ### Branch States -- **Active Development** - Feature work in progress -- **Ready for Review** - Code complete, PR created -- **In Review** - Undergoing code review process -- **Approved** - Approved and ready to merge -- **Merged** - Successfully merged to base branch -- **Archived** - Branch deleted after merge +Active Development → Ready for Review → In Review → Approved → Merged → Archived (deleted). ### Branch Protection Rules @@ -123,18 +60,7 @@ gh pr create --title "[US-123] feat: implement user authentication system" \ ### Cleanup Process -```bash -# After successful merge, delete local branch -git checkout main -git pull origin main -git branch -d feature/US-123-user-authentication - -# Delete remote branch (usually done automatically after PR merge) -git push origin --delete feature/US-123-user-authentication - -# Clean up tracking references -git remote prune origin -``` +After merge: delete the local and remote branch, then `git remote prune origin` (remote deletion is usually automatic after PR merge). ## Branch Management Guidelines @@ -147,129 +73,26 @@ git remote prune origin ### Short-Lived Branches -- **feature/xxx** - Individual feature development -- **bug/xxx** - Bug fix development -- **chore/xxx** - Maintenance and tooling work +- **feature/xxx**, **bug/xxx**, **chore/xxx** - Individual story, fix, or maintenance work; created from the base branch, deleted after merge. ### Branching Strategy -#### Git Flow Model +- **Git Flow**: features branch from `develop`; `release/*` and `hotfix/*` branch toward `main`. +- **GitHub Flow**: everything branches directly from `main`. -```text -main -├── develop -│ ├── feature/US-123-authentication -│ ├── feature/US-124-user-profile -│ └── feature/US-125-dashboard -├── release/v1.2.0 -└── hotfix/v1.1.1-critical-fix -``` - -#### GitHub Flow Model - -```text -main -├── feature/US-123-authentication -├── feature/US-124-user-profile -└── hotfix/critical-security-fix -``` - -### Branch Naming Conventions - -#### User Story Branches - -```text -feature/US-[story-number]-[brief-description] -feature/US-123-user-authentication -feature/US-124-profile-management -``` - -#### Bug Fix Branches - -```text -bug/BUG-[bug-number]-[brief-description] -bug/BUG-456-login-validation -bug/BUG-789-payment-error -``` - -#### Task Branches - -```text -chore/TASK-[task-number]-[brief-description] -chore/TASK-321-update-dependencies -chore/TASK-654-refactor-api-client -``` - -#### Hotfix Branches - -```text -hotfix/[severity]-[brief-description] -hotfix/critical-payment-processing -hotfix/security-user-data-leak -``` +The adopted strategy determines each branch type's base branch. ## Commit Strategy on Branches -### Atomic Commits - -Each commit should represent a single logical change: - -```bash -git commit -m "feat(auth): add JWT token generation" -git commit -m "test(auth): add authentication middleware tests" -git commit -m "docs(auth): update API documentation for auth endpoints" -``` - -### Commit Message Format - -```text -(): - - - - -``` - -### Pre-Commit Checklist - -- [ ] Code compiles without errors -- [ ] All tests pass locally -- [ ] Code follows style guidelines -- [ ] Documentation updated if needed -- [ ] No sensitive data in commit -- [ ] Commit message follows standards +Commits on branches follow the [commit template](commit-template.md): atomic commits, standard message format, pre-commit checklist (tests pass, style clean, no sensitive data). ## Collaboration Guidelines -### Branch Ownership - - **Primary Developer** - Creates and owns the branch -- **Collaborators** - Can contribute with permission +- **Collaborators** - Can contribute with permission (pull, commit, push on the shared branch) - **Reviewers** - Review code but don't commit directly -### Collaboration Commands - -```bash -# Add collaborator to branch -git checkout feature/US-123-authentication -git pull origin feature/US-123-authentication - -# Make changes and push -git add . -git commit -m "feat(auth): add additional validation" -git push origin feature/US-123-authentication -``` - -### Conflict Resolution - -```bash -# When conflicts occur during rebase/merge -git status # Check conflicted files -# Edit files to resolve conflicts -git add . -git rebase --continue # or git merge --continue -git push origin feature/US-123-authentication --force-with-lease -``` +Conflicts are resolved by the branch owner during rebase/merge, then pushed with `--force-with-lease`. ## Quality Assurance @@ -283,127 +106,11 @@ git push origin feature/US-123-authentication --force-with-lease - [ ] No merge commits in feature branch - [ ] Branch is up to date with base branch -### Automated Checks - -- **CI/CD Pipeline** - Runs on every push -- **Code Quality** - Linting and formatting checks -- **Security Scan** - Dependency and code security -- **Test Coverage** - Maintains minimum coverage threshold - -### Manual Review Points - -- **Code Standards** - Follows team conventions -- **Architecture** - Aligns with system design -- **Performance** - No performance regressions -- **Security** - No security vulnerabilities +Automated checks (CI/CD, linting, security scan, coverage) and review standards are defined in the [quality-assurance guidelines](../../quality-assurance/README.md). ## Troubleshooting -### Common Issues - -#### Branch Diverged from Base - -```bash -# Solution: Rebase onto latest base -git checkout main -git pull origin main -git checkout feature/US-123-authentication -git rebase main -``` - -#### Force Push After Rebase - -```bash -# Use force-with-lease for safety -git push origin feature/US-123-authentication --force-with-lease -``` - -#### Branch Name Conflicts - -```bash -# Rename local branch -git branch -m old-branch-name new-branch-name - -# Delete old remote branch and push new one -git push origin --delete old-branch-name -git push -u origin new-branch-name -``` - -#### Lost Commits After Rebase - -```bash -# Use reflog to find lost commits -git reflog -git checkout [commit-hash] -git checkout -b recovery-branch -``` - -### Emergency Procedures - -#### Revert Branch Changes - -```bash -# Revert last commit -git revert HEAD - -# Revert multiple commits -git revert HEAD~3..HEAD - -# Hard reset to specific commit (use with caution) -git reset --hard [commit-hash] -``` - -#### Emergency Hotfix Process - -```bash -# Create hotfix branch from main -git checkout main -git pull origin main -git checkout -b hotfix/critical-security-fix - -# Make minimal fix -# Test thoroughly -# Create emergency PR with expedited review -``` - ---- - -## Branch Templates for Different Types - -### Feature Branch Template - -```text -Branch: feature/US-[ID]-[description] -Purpose: Implement new functionality -Base: develop (or main for GitHub Flow) -Lifecycle: Create → Develop → PR → Review → Merge → Delete -``` - -### Bug Fix Branch Template - -```text -Branch: bug/BUG-[ID]-[description] -Purpose: Fix identified issues -Base: develop (or main for hotfixes) -Lifecycle: Create → Fix → Test → PR → Review → Merge → Delete -``` - -### Chore Branch Template - -```text -Branch: chore/TASK-[ID]-[description] -Purpose: Maintenance, refactoring, tooling -Base: develop (or main) -Lifecycle: Create → Work → PR → Review → Merge → Delete -``` - -### Release Branch Template - -```text -Branch: release/v[version] -Purpose: Release preparation and stabilization -Base: develop -Lifecycle: Create → Stabilize → Merge to main → Tag → Delete -``` - -This branch template provides comprehensive guidance for professional Git workflow management, ensuring consistent practices across all development activities. +- **Branch diverged from base**: rebase onto the latest base branch. +- **Push rejected after rebase**: `git push --force-with-lease`. +- **Lost commits after rebase**: recover via `git reflog`. +- **Emergency hotfix**: branch `hotfix/-` from `main`, minimal fix, expedited PR review. diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md index 18aedf0a..7cacec41 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/code-review-template.md @@ -190,11 +190,7 @@ Performance Tests: ✅ Within Limits / ⚠️ Degradation Detected ### Code Improvements ```diff -// Current implementation -- if (user != null && user.isActive() == true) { -+ if (user?.isActive()) { - // Process user -} +[Suggested code change in diff format] ``` ### Architecture Suggestions @@ -281,112 +277,4 @@ Performance Tests: ✅ Within Limits / ⚠️ Degradation Detected --- -## Review Templates for Different Types - -### Feature Review Template - -```markdown -## Feature Review: [Feature Name] - -**User Story:** [US-XXX] -**Business Value:** [Expected value delivery] - -### Functionality Validation - -- [ ] Feature matches acceptance criteria -- [ ] User experience is intuitive -- [ ] Edge cases handled appropriately - -### Implementation Quality - -- [ ] Code is clean and maintainable -- [ ] Architecture aligns with system design -- [ ] Performance meets requirements -``` - -### Bug Fix Review Template - -```markdown -## Bug Fix Review: [Bug Description] - -**Bug ID:** [BUG-XXX] -**Severity:** [Critical/High/Medium/Low] -**Root Cause:** [Identified cause] - -### Fix Validation - -- [ ] Root cause properly addressed -- [ ] Fix doesn't introduce new issues -- [ ] Regression test added - -### Quality Assurance - -- [ ] Minimal changes made -- [ ] All related scenarios tested -- [ ] Documentation updated if needed -``` - -### Refactoring Review Template - -```markdown -## Refactoring Review: [Code Area] - -**Objective:** [Refactoring goal] -**Scope:** [What's being refactored] - -### Refactoring Quality - -- [ ] Code readability improved -- [ ] Performance maintained or improved -- [ ] Functionality unchanged -- [ ] Test coverage maintained - -### Risk Assessment - -- [ ] No breaking changes introduced -- [ ] Backward compatibility maintained -- [ ] Deployment risk minimized -``` - -### Hotfix Review Template - -```markdown -## HOTFIX Review: [Critical Issue] - -**Severity:** CRITICAL -**Issue:** [Production problem] -**Impact:** [Business/user impact] - -### Emergency Review Focus - -- [ ] Fix addresses immediate problem -- [ ] Minimal change approach used -- [ ] Risk of new issues minimized -- [ ] Rollback plan ready - -### Expedited Process - -- [ ] Priority reviewer assigned -- [ ] Fast-track approval process -- [ ] Emergency deployment prepared -``` - -## Review Quality Standards - -### Effective Review Practices - -1. **Be Constructive** - Focus on code, not the person -2. **Be Specific** - Provide clear, actionable feedback -3. **Be Timely** - Complete reviews within agreed timeframes -4. **Be Thorough** - Cover all aspects systematically -5. **Be Educational** - Share knowledge and best practices - -### Review Communication Guidelines - -- **Use positive language** - Frame feedback constructively -- **Explain the why** - Provide reasoning for suggestions -- **Offer solutions** - Don't just identify problems -- **Ask questions** - Seek understanding before criticizing -- **Acknowledge good work** - Recognize quality implementations - -This code review template ensures thorough, consistent, and constructive code reviews that maintain high code quality standards while supporting team learning and collaboration. +For review type emphasis: Feature → acceptance criteria and UX; Bug Fix → root cause addressed + regression test; Refactoring → behavior unchanged, coverage maintained; Hotfix → minimal change, rollback ready. Review conduct standards: see [team standards](../team/standards.md) (single source of truth). diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/commit-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/commit-template.md index 787e0535..a06e10e2 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/commit-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/commit-template.md @@ -65,9 +65,7 @@ Refs: #T-456 Refs: #T-456 ``` -## Commit Message Examples - -### Feature Implementation +## Commit Message Example ```text [US-789] feat: add real-time notifications system @@ -76,72 +74,13 @@ Implement WebSocket-based notification delivery: - Add WebSocket server configuration - Create notification event handlers - Implement client-side notification display -- Add notification persistence to database -This enables users to receive instant updates without page refresh, -improving user engagement and system responsiveness. +This enables users to receive instant updates without page refresh. Refs: #T-234, #T-235 ``` -### Bug Fix - -```text -[US-456] fix: resolve memory leak in data processing - -- Fix unclosed database connections in batch processor -- Add proper cleanup in error handling paths -- Implement connection pooling timeout -- Add memory usage monitoring - -The memory leak was causing application crashes during large -data imports. This fix ensures proper resource cleanup and -adds monitoring to prevent future issues. - -Closes #BUG-123 -``` - -### Refactoring - -```text -[US-321] refactor: restructure user management module - -- Extract user validation into separate service -- Simplify user creation workflow -- Improve error handling consistency -- Add comprehensive unit test coverage - -No functional changes - purely code organization improvement -for better maintainability and testability. - -Refs: #T-567 -``` - -### Documentation - -```text -[US-654] docs: add API documentation for user endpoints - -- Document authentication endpoints -- Add request/response examples -- Include error code explanations -- Add usage examples for common scenarios - -Refs: #T-890 -``` - -### Configuration/Setup - -```text -[US-987] chore: configure production deployment pipeline - -- Add Docker configuration for production -- Set up environment variable management -- Configure health check endpoints -- Add logging and monitoring setup - -Refs: #T-111 -``` +The same structure applies to every type (fix, refactor, docs, chore, ...): subject line, optional body with bullets explaining what and why, optional footer with references. ## Commit Message Guidelines @@ -189,46 +128,7 @@ Format: [BUG-###] - Bug tracking number Example: Closes #BUG-123 ``` -## Non-Code Task Commits - -### Documentation Tasks - -```text -[US-456] docs: update user onboarding guide - -- Add screenshots for new UI elements -- Update step-by-step instructions -- Include troubleshooting section -- Add FAQ for common issues - -Refs: #T-789 -``` - -### Configuration Changes - -```text -[US-123] chore: update project configuration - -- Configure ESLint rules for TypeScript -- Add Prettier formatting configuration -- Update package.json scripts -- Add VS Code workspace settings - -Refs: #T-234 -``` - -### Infrastructure Setup - -```text -[US-789] build: setup CI/CD pipeline - -- Add GitHub Actions workflow configuration -- Configure automated testing on pull requests -- Set up deployment to staging environment -- Add code quality checks - -Refs: #T-345 -``` +Non-code tasks (documentation, configuration, infrastructure) follow the same format with the matching type (`docs`, `chore`, `build`, `ci`). ## Quality Checklist @@ -257,39 +157,12 @@ Before committing, ensure: ## Atomic Commit Principles -### Single Responsibility - -Each commit should represent one logical change: - -- ✅ Good: Fix one specific bug -- ❌ Bad: Fix bug + add new feature + update documentation - -### Complete Functionality - -Commits should leave the codebase in a working state: - -- ✅ Good: Complete feature implementation with tests -- ❌ Bad: Partial implementation that breaks build - -### Meaningful Scope - -Commit scope should be appropriately sized: - -- ✅ Good: Implement one component or fix one issue -- ❌ Bad: Massive commit touching unrelated areas +- **Single responsibility**: one logical change per commit (not bug fix + feature + docs together) +- **Complete functionality**: each commit leaves the codebase in a working state +- **Meaningful scope**: one component or one issue — never a massive commit touching unrelated areas ## Branch and Merge Strategy -### Feature Branch Commits - -```text -# During feature development -[US-123] test: add failing tests for user search -[US-123] feat: implement basic search functionality -[US-123] refactor: optimize search performance -[US-123] docs: document search API endpoints -``` - ### Squash Merge Strategy When using squash merge, final commit should summarize the feature: @@ -309,72 +182,12 @@ Closes #T-234, #T-235, #T-236 ### Merge Commit Strategy -When preserving commit history, ensure each commit follows guidelines: - -```text -# Each commit in the branch should be clean and follow standards -[US-123] test: add unit tests for search service -[US-123] feat: implement search backend API -[US-123] feat: create search UI components -[US-123] refactor: optimize search query performance -``` +When preserving commit history, each commit in the branch must be clean and follow the standards above. --- ## Common Anti-Patterns to Avoid -### Poor Commit Messages - -❌ **Bad Examples:** - -```text -fix stuff -WIP -asdf -update code -fix bug -``` - -✅ **Good Examples:** - -```text -[US-123] fix: resolve null pointer in user validation -[US-456] feat: add email notification service -[US-789] refactor: extract common validation logic -``` - -### Inappropriate Grouping - -❌ **Bad:** Mixed unrelated changes - -```text -[US-123] feat: add user search + fix login bug + update docs -``` - -✅ **Good:** Separate logical commits - -```text -[US-123] feat: add user search functionality -[US-124] fix: resolve login validation error -[US-123] docs: update search API documentation -``` - -### Missing Context - -❌ **Bad:** No explanation for complex changes - -```text -[US-123] refactor: change user service -``` - -✅ **Good:** Clear explanation of reasoning - -```text -[US-123] refactor: extract user validation to separate service - -- Move validation logic from controller to dedicated service -- Improve testability and code reuse -- Prepare for upcoming role-based permissions feature - -Refs: #T-456 -``` +❌ Vague messages (`fix stuff`, `WIP`, `update code`) — ✅ `[US-123] fix: resolve null pointer in user validation` +❌ Mixed unrelated changes in one commit — ✅ separate logical commits per story/type +❌ Complex change with no body — ✅ body explaining what and why, with refs diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/epic-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/epic-template.md index 3fc1183b..8e6a8fee 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/epic-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/epic-template.md @@ -31,17 +31,11 @@ ### Success Metrics (KPIs) -- **Business Metric 1:** [Metric name] - Target: [target value] +- **Business Metric N:** [Metric name] - Target: [target value] - **Measurement method:** [How this will be tracked] - **Current baseline:** [Current performance level] -- **Business Metric 2:** [Metric name] - Target: [target value] - - **Measurement method:** [Tracking approach] - - **Current baseline:** [Starting point] - -- **Business Metric 3:** [Metric name] - Target: [target value] - - **Measurement method:** [Measurement strategy] - - **Current baseline:** [Current state] +[Repeat per metric] ### Return on Investment (ROI) @@ -69,31 +63,24 @@ ### Pain Points Addressed -1. **Pain Point 1:** [Specific customer or business problem] +1. **Pain Point N:** [Specific customer or business problem] - **Impact:** [Cost, frustration, or inefficiency caused] - **Frequency:** [How often this problem occurs] -2. **Pain Point 2:** [Another critical issue] - - **Impact:** [Business or user impact] - - **Frequency:** [Occurrence rate] +[Repeat per pain point] ## Target Users & Personas ### Primary Users -**Persona 1:** [Primary user type] +**Persona N:** [User type] - **Demographics:** [Age, role, experience level] - **Goals:** [What they want to achieve] - **Frustrations:** [Current challenges they face] - **Usage Patterns:** [How they interact with the system] -**Persona 2:** [Secondary user type] - -- **Demographics:** [Relevant characteristics] -- **Goals:** [Their objectives] -- **Frustrations:** [Pain points] -- **Usage Patterns:** [Interaction preferences] +[Repeat per persona] ### User Journey @@ -107,17 +94,11 @@ ### Key Capabilities -1. **Capability 1:** [Major functionality or feature area] +1. **Capability N:** [Major functionality or feature area] - **Description:** [What this capability provides] - **Value:** [Why this is important for users] -2. **Capability 2:** [Another core capability] - - **Description:** [Functionality description] - - **Value:** [User and business value] - -3. **Capability 3:** [Additional key capability] - - **Description:** [What it enables] - - **Value:** [Impact and importance] +[Repeat per capability] ### Solution Differentiators @@ -129,14 +110,11 @@ ### Themes & Feature Areas -1. **Theme 1:** [Logical grouping of related features] - - [Feature/Story area 1.1] - - [Feature/Story area 1.2] - - [Feature/Story area 1.3] +1. **Theme N:** [Logical grouping of related features] + - [Feature/Story area N.1] + - [Feature/Story area N.2] -2. **Theme 2:** [Another feature grouping] - - [Feature/Story area 2.1] - - [Feature/Story area 2.2] +[Repeat per theme] ### User Stories (High-Level) @@ -146,9 +124,7 @@ - **Story points:** [Estimate] - **Dependencies:** [Key dependencies] -- [ ] **US-XXX:** As a [user] I want [capability] so that [benefit] - - **Story points:** [Estimate] - - **Dependencies:** [Dependencies] +[Repeat per story] #### Should-Have Stories (P1) @@ -187,8 +163,7 @@ | Risk | Impact | Probability | Mitigation Strategy | | ------------------ | --------------- | --------------- | ------------------------- | -| [Technical risk 1] | High/Medium/Low | High/Medium/Low | [Technical mitigation] | -| [Technical risk 2] | High/Medium/Low | High/Medium/Low | [Risk reduction approach] | +| [Technical risk] | High/Medium/Low | High/Medium/Low | [Technical mitigation] | ### Infrastructure & Tooling @@ -244,15 +219,12 @@ ### Critical Path Dependencies -- [ ] **Dependency 1:** [Critical external dependency] +- [ ] **Dependency N:** [Critical external dependency] - **Owner:** [Responsible team/person] - **Required by:** [Date] - **Risk level:** [High/Medium/Low] -- [ ] **Dependency 2:** [Another critical dependency] - - **Owner:** [Responsible party] - - **Required by:** [Deadline] - - **Risk level:** [Risk assessment] +[Repeat per dependency] ### Release Strategy @@ -267,22 +239,19 @@ | Risk | Impact | Probability | Mitigation Strategy | Owner | | ----------------- | --------------- | --------------- | --------------------- | -------- | -| [Business risk 1] | High/Medium/Low | High/Medium/Low | [Business mitigation] | [Person] | -| [Market risk] | High/Medium/Low | High/Medium/Low | [Market strategy] | [Person] | +| [Business risk] | High/Medium/Low | High/Medium/Low | [Business mitigation] | [Person] | ### Technical Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | | ------------------ | --------------- | --------------- | ---------------------- | -------- | -| [Technical risk 1] | High/Medium/Low | High/Medium/Low | [Technical solution] | [Person] | -| [Integration risk] | High/Medium/Low | High/Medium/Low | [Integration approach] | [Person] | +| [Technical risk] | High/Medium/Low | High/Medium/Low | [Technical solution] | [Person] | ### Resource Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | | --------------------- | --------------- | --------------- | ---------------------- | -------- | -| [Resource constraint] | High/Medium/Low | High/Medium/Low | [Resource plan] | [Person] | -| [Skill gap] | High/Medium/Low | High/Medium/Low | [Training/hiring plan] | [Person] | +| [Resource risk] | High/Medium/Low | High/Medium/Low | [Resource plan] | [Person] | ## Success Validation diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md index b7b5004f..85627334 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/initiative-template.md @@ -48,22 +48,13 @@ ### Primary Business Goals -1. **Objective 1:** [Specific, measurable business objective] +1. **Objective N:** [Specific, measurable business objective] - **Target:** [Quantified target with timeline] - **Baseline:** [Current performance level] - **Impact:** [Expected business impact] -2. **Objective 2:** [Another key business objective] - - - **Target:** [Measurable target] - - **Baseline:** [Starting point] - - **Impact:** [Business value] - -3. **Objective 3:** [Additional strategic objective] - - **Target:** [Specific target] - - **Baseline:** [Current state] - - **Impact:** [Expected outcome] +[Repeat per objective] ### Success Metrics & KPIs @@ -85,19 +76,14 @@ ### Customer Segments -**Primary Segment:** [Primary customer segment] +**[Primary | Secondary] Segment:** [Customer segment] - **Size:** [Market size and addressable population] - **Characteristics:** [Key demographic and behavioral traits] - **Current Pain Points:** [Major challenges and frustrations] - **Value Proposition:** [How initiative addresses their needs] -**Secondary Segment:** [Secondary customer segment] - -- **Size:** [Segment size] -- **Characteristics:** [Relevant traits] -- **Current Pain Points:** [Challenges] -- **Value Proposition:** [Value delivered] +[Repeat per segment] ### Customer Journey Impact @@ -117,16 +103,13 @@ ### Key Solution Components -1. **Component 1:** [Major solution area or capability] +1. **Component N:** [Major solution area or capability] - **Description:** [What this component delivers] - **Value:** [Business and customer value] - **Timeline:** [Development timeframe] -2. **Component 2:** [Another key solution component] - - **Description:** [Component description] - - **Value:** [Value proposition] - - **Timeline:** [Delivery timeline] +[Repeat per component] ### Innovation & Differentiation @@ -147,11 +130,7 @@ - **Timeline:** [Expected delivery window] - **Dependencies:** [Key dependencies] -- [ ] **EP-XXX:** [Another critical epic] - - **Business Value:** [Value delivered] - - **Epic Points:** [Size estimate] - - **Timeline:** [Delivery timeframe] - - **Dependencies:** [Dependencies] +[Repeat per epic — same fields for each priority tier below] #### Medium-Priority Epics (Should-Have) @@ -251,24 +230,19 @@ | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | ------------------ | ------------ | ------------ | ---------------------- | -------- | -------- | -| [Market risk] | High/Med/Low | High/Med/Low | [Market mitigation] | [Person] | [When] | -| [Competitive risk] | High/Med/Low | High/Med/Low | [Competitive strategy] | [Person] | [When] | -| [Technology risk] | High/Med/Low | High/Med/Low | [Tech mitigation] | [Person] | [When] | +| [Strategic risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ### Execution Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | --------------- | ------------ | ------------ | --------------------- | -------- | -------- | -| [Resource risk] | High/Med/Low | High/Med/Low | [Resource plan] | [Person] | [When] | -| [Timeline risk] | High/Med/Low | High/Med/Low | [Schedule mitigation] | [Person] | [When] | -| [Quality risk] | High/Med/Low | High/Med/Low | [Quality assurance] | [Person] | [When] | +| [Execution risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ### Financial Risks | Risk | Impact | Probability | Mitigation Strategy | Owner | Timeline | | ---------------- | ------------ | ------------ | -------------------- | -------- | -------- | -| [Budget overrun] | High/Med/Low | High/Med/Low | [Budget controls] | [Person] | [When] | -| [ROI shortfall] | High/Med/Low | High/Med/Low | [Value optimization] | [Person] | [When] | +| [Financial risk] | High/Med/Low | High/Med/Low | [Mitigation] | [Person] | [When] | ## Go-to-Market Strategy @@ -338,23 +312,11 @@ ### Communication Plan -#### Executive Updates: - -- **Frequency:** [How often executive updates occur] -- **Format:** [Update format and content] -- **Audience:** [Who receives executive updates] - -#### Team Communication: - -- **Frequency:** [Team communication rhythm] -- **Format:** [Team update format] -- **Audience:** [Extended team and stakeholders] - -#### Organization Communication: - -- **Frequency:** [Company-wide communication schedule] -- **Format:** [Organizational update approach] -- **Audience:** [Broader organization] +| Level | Frequency | Format | Audience | +| ------------------ | ----------- | -------- | ---------- | +| **Executive** | [How often] | [Format] | [Who] | +| **Team** | [Rhythm] | [Format] | [Who] | +| **Organization** | [Schedule] | [Format] | [Who] | ### Decision-Making Framework diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/pr-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/pr-template.md index 9871dd25..82664511 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/pr-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/pr-template.md @@ -248,12 +248,7 @@ Impact: [Improvement/degradation percentage] ### Testing the Changes ```bash -# Steps to test this PR locally -git checkout [branch-name] -npm install # or relevant dependency installation -npm run test # run test suite -npm run start # start local development -# Navigate to [specific URLs] to test functionality +[Commands to test this PR locally: checkout, install, test, run] ``` ### Key Test Scenarios @@ -299,126 +294,7 @@ npm run start # start local development --- -## Templates for Different PR Types - -### Feature PR Template - -```markdown -## Feature Implementation: [Feature Name] - -**User Story:** [US-XXX] -**Epic:** [EP-XXX] - -### What's New - -[Description of new functionality added] - -### User Impact - -[How this improves user experience] - -### Technical Implementation - -[Key technical decisions and approaches] -``` - -### Bug Fix PR Template - -```markdown -## Bug Fix: [Issue Description] - -**Bug Report:** [BUG-XXX] -**Severity:** [Critical/High/Medium/Low] - -### Problem - -[Description of the bug and its impact] - -### Root Cause - -[Explanation of what caused the issue] - -### Solution - -[How the fix addresses the root cause] - -### Verification - -[How the fix was tested and verified] -``` - -### Refactoring PR Template - -```markdown -## Refactoring: [Code Area] - -**Story:** [US-XXX] -**Type:** Code Quality Improvement - -### Motivation - -[Why this refactoring was needed] - -### Changes Made - -[What was restructured or improved] - -### Benefits - -[Improved maintainability, performance, or readability] - -### Risk Assessment - -[Low risk - no functional changes] -``` - -### Documentation PR Template - -```markdown -## Documentation Update: [Documentation Area] - -**Story:** [US-XXX] -**Type:** Documentation - -### Documentation Changes - -[What documentation was added or updated] - -### Target Audience - -[Who will benefit from this documentation] - -### Coverage - -[What areas are now better documented] -``` - -### Hotfix PR Template - -```markdown -## HOTFIX: [Critical Issue] - -**Severity:** CRITICAL -**Issue:** [Production issue description] - -### Immediate Problem - -[What is broken in production] - -### Quick Fix - -[Minimal change to resolve immediate issue] - -### Full Solution Plan - -[Link to planned comprehensive fix] - -### Rollback Plan - -[How to quickly rollback if needed] -``` - ---- +Type emphasis: Feature → user impact + technical decisions; Bug Fix → problem, root cause, solution, verification; Refactoring → motivation + no functional changes; Documentation → audience + coverage; Hotfix → immediate problem, minimal fix, rollback plan. ## Pre-Submission Checklist diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/user-story-template.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/user-story-template.md index 0538310e..3cc2c60e 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/user-story-template.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/collaboration/templates/user-story-template.md @@ -85,7 +85,7 @@ > **Section ordering**: Functional sections first, technical sections last. > Technical Analysis is positioned at the end as the bridge to Task Breakdown -> (appended by `/plan-tasks`). +> (appended by `/pair-process-plan-tasks`). ```markdown ## Story Statement diff --git a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/user-experience/markdown-templates.md b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/user-experience/markdown-templates.md index 555c5492..4e59c3da 100644 --- a/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/user-experience/markdown-templates.md +++ b/packages/knowledge-hub/dataset/.pair/knowledge/guidelines/user-experience/markdown-templates.md @@ -2,30 +2,11 @@ ## Introduction -Markdown templates provide standardized formats for documentation, content creation, and communication across design and development workflows. These templates ensure consistency, improve efficiency, and maintain quality standards while facilitating collaboration between team members and stakeholders. +Markdown templates provide standardized formats for documentation, content creation, and communication across design and development workflows. ## Scope -### In Scope - -- Documentation template creation and maintenance -- Content structure standardization -- Design system documentation templates -- User story and requirement templates -- Process documentation frameworks -- Meeting notes and decision record templates -- Design review and handoff templates -- Quality assurance and testing templates -- Project communication templates -- Knowledge base article templates - -### Out of Scope - -- Content writing training -- Markdown syntax education -- Platform-specific implementation -- Content strategy development -- Editorial workflow management +**In scope**: documentation, design system, process, UX research, and project management templates. **Out of scope**: content writing training, markdown syntax education, platform-specific implementation, content strategy. ## Template Categories @@ -411,128 +392,10 @@ Description of process experiment to try. ## Content Standards -### Writing Guidelines - -#### Voice and Tone - -- Clear and concise language -- Active voice preference -- Professional yet approachable tone -- Consistent terminology usage -- Inclusive language practices - -#### Structure Principles - -- Logical information hierarchy -- Scannable content organization -- Consistent heading levels -- Bullet points for lists -- Tables for structured data - -#### Formatting Standards - -- Consistent heading styles -- Proper link formatting -- Code block usage -- Image alt text inclusion -- Table header definitions - -### Template Maintenance - -#### Version Control - -- Template versioning system -- Change tracking and history -- Update notification process -- Approval workflow for changes -- Archive management - -#### Quality Assurance - -- Regular template review -- Usage analytics monitoring -- Feedback collection -- Improvement identification -- Update implementation - -## Implementation Guidelines - -### Tool Integration - -#### Platform Compatibility - -- GitHub markdown compatibility -- Notion integration support -- Confluence adaptation -- Slack formatting consideration -- Email template variations - -#### Automation Opportunities - -- Template generation scripts -- Content validation tools -- Formatting automation -- Link checking systems -- Version update notifications - -### Team Adoption - -#### Training and Onboarding - -- Template usage training -- Best practice guidelines -- Example implementations -- Common mistake prevention -- Feedback collection methods - -#### Compliance Monitoring - -- Template usage tracking -- Quality standard enforcement -- Consistency checking -- Improvement suggestions -- Support provision - -## Best Practices - -### Content Creation - -- Start with template selection -- Follow established patterns -- Maintain consistency -- Include required sections -- Review before publishing - -### Template Evolution - -- Regular usage analysis -- Feedback integration -- Continuous improvement -- Version management -- Change communication - -### Team Collaboration - -- Shared template library -- Collaborative editing -- Review processes -- Knowledge sharing -- Standard adoption - -## Measurement and Analytics - -### Usage Metrics - -- Template adoption rates -- Content creation efficiency -- Quality improvement indicators -- Team satisfaction scores -- Process compliance rates +- **Voice and tone**: clear, concise, active voice, consistent and inclusive terminology. +- **Structure**: logical hierarchy, scannable organization, consistent heading levels, bullets for lists, tables for structured data. +- **Formatting**: proper link formatting, code blocks for code, image alt text, table headers. -### Continuous Improvement +## Template Maintenance -- Regular template audits -- User feedback integration -- Process optimization -- Tool integration enhancement -- Training effectiveness measurement +Templates are versioned with the knowledge base: propose changes via PR, review regularly, evolve from usage feedback. When creating content, start from the matching template, include its required sections, and review before publishing.