nitm-ai-dev-toolkit 3.0.15

package/src/monorepo/templates/README.md

@@ -0,0 +1,106 @@
+# Documentation Templates
+
+This folder contains templates for monorepo documentation. Copy these templates when creating new feature or fix documentation.
+
+## Available Templates
+
+- **monthly-fix-log.template.md** - Template for monthly fix logs (YYYY-MM.md format)
+- **feature-spec.template.md** - Template for feature specifications
+- **feature-plan.template.md** - Template for feature implementation plans
+- **complex-fix-spec.template.md** - Template for complex fix specifications
+- **complex-fix-plan.template.md** - Template for complex fix implementation plans
+- **adr.template.md** - Template for Architecture Decision Records (root docs only)
+
+## Usage
+
+### For App-Specific Documentation
+
+**Monthly Fix Logs:**
+
+```bash
+# Copy template to create new monthly log for web app
+cp templates/monthly-fix-log.template.md apps/web/docs/fixes/2026-01.md
+
+# Edit and replace {{APP_NAME}}, {{FRAMEWORK}}, dates, etc.
+```
+
+**Feature Documentation:**
+
+```bash
+# Create feature folder in web app
+mkdir -p apps/web/docs/features/ISSUE-123-FEATURE-NAME
+
+# Copy templates
+cp templates/feature-spec.template.md apps/web/docs/features/ISSUE-123-FEATURE-NAME/spec.md
+cp templates/feature-plan.template.md apps/web/docs/features/ISSUE-123-FEATURE-NAME/plan.md
+```
+
+**Complex Fix Documentation:**
+
+```bash
+# Create fix folder in server app
+mkdir -p apps/server/docs/fixes/ISSUE-456-COMPLEX-FIX
+
+# Copy templates
+cp templates/complex-fix-spec.template.md apps/server/docs/fixes/ISSUE-456-COMPLEX-FIX/spec.md
+cp templates/complex-fix-plan.template.md apps/server/docs/fixes/ISSUE-456-COMPLEX-FIX/plan.md
+```
+
+### For Root Documentation
+
+**Architecture Decision Records:**
+
+```bash
+# Copy ADR template to root docs
+cp templates/adr.template.md docs/architecture/0001-decision-title.md
+
+# Edit and replace placeholders
+```
+
+## Critical Guidelines
+
+### App-Specific vs Root Documentation
+
+**✅ Document in apps/packages:**
+
+- App-specific features
+- App-specific bug fixes
+- Component implementations
+- API endpoint changes
+
+**✅ Document in root docs/:**
+
+- Architecture decisions affecting multiple apps
+- Deployment pipelines
+- Cross-app integration patterns
+- Monorepo tooling configuration
+
+**❌ Never put app-specific docs in root docs/**
+
+See [documentation.instructions.md](../.github/instructions/documentation.instructions.md) for full guidelines.
+
+## Placeholder Reference
+
+### Common Placeholders
+
+- `{{APP_NAME}}` - App name (e.g., web, server)
+- `{{FRAMEWORK}}` - Framework (e.g., Nuxt, Hono)
+- `{{MONTH_NAME}}` - Full month name (e.g., January)
+- `{{YEAR}}` - Four-digit year (e.g., 2026)
+- `{{YYYY-MM-DD}}` - ISO date format
+- `{{LAST_DAY}}` - Last day of the month (e.g., 31)
+- `{{ISSUE_ID}}` - Issue tracker ID
+- `{{FEATURE_NAME}}` - Feature name
+- `{{FIX_NAME}}` - Fix name
+
+### Monorepo-Specific
+
+- `{{APP_1}}` - First app name from workspace
+- `{{APP_2}}` - Second app name from workspace
+- `{{PACKAGE_1}}` - First package name
+- `{{PACKAGE_2}}` - Second package name
+- `{{BUILD_SYSTEM}}` - Build system (e.g., Turborepo)
+
+## Automated Creation
+
+Use the `/spec` and `/plan` commands to automatically create documentation from these templates with placeholders filled in based on your monorepo structure.

package/src/monorepo/templates/adr.template.md

@@ -0,0 +1,156 @@
+# ADR-{{ADR_NUMBER}}: {{DECISION_TITLE}}
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** {{DATE}}
+**Author:** {{AUTHOR}}
+**Deciders:** {{DECIDERS}}
+**Technical Story:** {{ISSUE_ID}}
+
+## Context
+
+Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?
+
+### Background
+
+Provide any relevant background information:
+
+- Current state of the system
+- Technical constraints
+- Business requirements
+- Timeline pressures
+
+### Problem Statement
+
+In 1-2 sentences, what problem are we trying to solve?
+
+## Decision Drivers
+
+What factors are important in making this decision?
+
+- **Driver 1:** Description
+- **Driver 2:** Description
+- **Driver 3:** Description
+- **Driver 4:** Description
+
+## Considered Options
+
+### Option 1: {{OPTION_1_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+### Option 2: {{OPTION_2_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+### Option 3: {{OPTION_3_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+## Decision Outcome
+
+### Chosen Option
+
+**Option X: {{CHOSEN_OPTION_NAME}}**
+
+### Rationale
+
+Explain why this option was chosen:
+
+- Reason 1
+- Reason 2
+- Reason 3
+
+### Trade-offs Accepted
+
+What are we giving up by choosing this option?
+
+- Trade-off 1
+- Trade-off 2
+
+## Consequences
+
+### Positive
+
+- Positive consequence 1
+- Positive consequence 2
+
+### Negative
+
+- Negative consequence 1
+- Negative consequence 2
+
+### Neutral
+
+- Neutral consequence 1
+
+## Implementation
+
+### Action Items
+
+- [ ] Action item 1
+- [ ] Action item 2
+- [ ] Action item 3
+
+### Migration Plan
+
+If applicable, describe how to migrate from current state to new state.
+
+### Rollback Plan
+
+If applicable, describe how to rollback if needed.
+
+## Validation
+
+How will we know if this decision was successful?
+
+- Success metric 1
+- Success metric 2
+
+## Related Decisions
+
+- [ADR-XXX](./ADR-XXX-title.md) - Related decision
+- [ADR-YYY](./ADR-YYY-title.md) - Superseded by this ADR
+
+## References
+
+- [Link to relevant documentation]
+- [Link to technical specification]
+- [Link to discussion thread]
+
+---
+
+## Changelog
+
+| Date       | Change                              |
+| ---------- | ----------------------------------- |
+| {{DATE}}   | Initial proposal                    |

package/src/monorepo/templates/complex-fix-plan.template.md

@@ -0,0 +1,154 @@
+# Fix Implementation Plan: {{FIX_NAME}}
+
+**Issue:** {{ISSUE_ID}}
+**Spec:** [spec.md](spec.md)
+**Author:** {{AUTHOR}}
+**Created:** {{DATE}}
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Status:** Planning | In Progress | In Review | Deployed
+
+## Overview
+
+Brief summary of the fix and implementation approach.
+
+## Prerequisites
+
+- [ ] Root cause confirmed in spec
+- [ ] Impact assessment complete
+- [ ] Stakeholders notified
+- [ ] Rollback plan ready
+
+## Implementation Steps
+
+### Step 1: Immediate Mitigation (if needed)
+
+**Timeline:** ASAP
+
+**Tasks:**
+- [ ] Apply temporary workaround
+- [ ] Notify affected users
+- [ ] Enable monitoring
+
+### Step 2: Prepare Fix
+
+**Timeline:** X hours
+
+**Files to modify:**
+- `path/to/file1.{{FILE_EXTENSION}}`
+- `path/to/file2.{{FILE_EXTENSION}}`
+
+**Tasks:**
+- [ ] Create feature branch from {{DEFAULT_BRANCH}}
+- [ ] Implement code changes
+- [ ] Add/update tests
+- [ ] Update documentation
+
+**Code Changes:**
+
+```{{FILE_EXTENSION}}
+// Describe the key changes
+```
+
+### Step 3: Testing
+
+**Timeline:** X hours
+
+**Tasks:**
+- [ ] Run unit tests
+- [ ] Run integration tests
+- [ ] Manual verification of fix
+- [ ] Verify no regression
+
+**Test Commands:**
+```bash
+{{TEST_COMMAND}}
+```
+
+### Step 4: Code Review
+
+**Timeline:** X hours
+
+**Tasks:**
+- [ ] Create pull request
+- [ ] Address review comments
+- [ ] Get approval from {{REVIEWER}}
+
+### Step 5: Deployment
+
+**Timeline:** X hours
+
+**Tasks:**
+- [ ] Deploy to staging
+- [ ] Verify fix in staging
+- [ ] Deploy to production
+- [ ] Monitor for 24 hours
+
+## Rollback Plan
+
+If the fix causes issues:
+
+1. **Immediate:** Revert commit `{{COMMIT_HASH}}`
+2. **Database:** Run rollback migration (if applicable)
+3. **Cache:** Clear cache keys: `{{CACHE_KEYS}}`
+4. **Notify:** Alert team via {{NOTIFICATION_CHANNEL}}
+
+**Rollback command:**
+```bash
+git revert {{COMMIT_HASH}}
+{{DEPLOY_COMMAND}}
+```
+
+## Verification
+
+### Success Criteria
+
+- [ ] Original bug no longer reproducible
+- [ ] No new errors in logs
+- [ ] Performance metrics stable
+- [ ] User reports resolved
+
+### Monitoring
+
+| Metric              | Expected Value | Alert Threshold |
+| ------------------- | -------------- | --------------- |
+| Error rate          | < 0.1%         | > 1%            |
+| Response time       | < 200ms        | > 500ms         |
+
+## Communication
+
+### Stakeholder Updates
+
+| Stakeholder      | Update Method | When             |
+| ---------------- | ------------- | ---------------- |
+| Engineering      | Slack         | On fix complete  |
+| Product          | Email         | On deployment    |
+| Customers        | Status page   | If applicable    |
+
+### Post-Mortem
+
+- [ ] Schedule post-mortem meeting
+- [ ] Document lessons learned
+- [ ] Create follow-up tickets for improvements
+
+## Timeline
+
+| Phase                | Target Time    | Actual Time | Status      |
+| -------------------- | -------------- | ----------- | ----------- |
+| Mitigation           | +1 hour        |             | Not Started |
+| Fix Development      | +4 hours       |             | Not Started |
+| Testing              | +2 hours       |             | Not Started |
+| Code Review          | +2 hours       |             | Not Started |
+| Deployment           | +1 hour        |             | Not Started |
+| Monitoring           | +24 hours      |             | Not Started |
+
+## Notes
+
+Additional notes, edge cases discovered, or decisions made during implementation.
+
+---
+
+## Progress Log
+
+| Time       | Update                              |
+| ---------- | ----------------------------------- |
+| {{TIME}}   | Plan created                        |

package/src/monorepo/templates/complex-fix-spec.template.md

@@ -0,0 +1,160 @@
+# Fix Specification: {{FIX_NAME}}
+
+**Issue:** {{ISSUE_ID}}
+**Author:** {{AUTHOR}}
+**Created:** {{DATE}}
+**Severity:** Critical | High | Medium | Low
+**Status:** Investigating | Root Cause Found | Fix In Progress | Resolved
+
+## Problem Summary
+
+Brief one-paragraph description of the bug or issue.
+
+## Symptoms
+
+### Observed Behavior
+
+What users or systems are experiencing:
+
+- Symptom 1
+- Symptom 2
+- Symptom 3
+
+### Expected Behavior
+
+What should happen instead:
+
+- Expected behavior 1
+- Expected behavior 2
+
+### Reproduction Steps
+
+1. Step 1
+2. Step 2
+3. Step 3
+4. Observe: [describe the bug]
+
+### Environment
+
+- **Environment:** Production / Staging / Development
+- **Version:** {{VERSION}}
+- **Browser/OS:** (if applicable)
+- **User Impact:** X users affected
+
+## Root Cause Analysis
+
+### Investigation Timeline
+
+| Time       | Action                        | Finding                    |
+| ---------- | ----------------------------- | -------------------------- |
+| {{TIME}}   | Reviewed logs                 | Found error pattern        |
+| {{TIME}}   | Checked database              | Data inconsistency found   |
+
+### Root Cause
+
+Detailed explanation of why the bug occurred:
+
+```
+[Code snippet or configuration showing the root cause]
+```
+
+**Why it happened:**
+- Reason 1
+- Reason 2
+
+### Contributing Factors
+
+- Factor 1 (e.g., missing validation)
+- Factor 2 (e.g., race condition)
+- Factor 3 (e.g., edge case not handled)
+
+## Impact Assessment
+
+### Affected Components
+
+| Component        | Impact Level | Description           |
+| ---------------- | ------------ | --------------------- |
+| {{COMPONENT_1}}  | High/Med/Low | How it's affected     |
+| {{COMPONENT_2}}  | High/Med/Low | How it's affected     |
+
+### Data Impact
+
+- Was any data corrupted? Yes / No
+- If yes, describe scope and recovery plan
+
+### Business Impact
+
+- Users affected: X
+- Revenue impact: $X or N/A
+- SLA breach: Yes / No
+
+## Proposed Solution
+
+### Approach
+
+Describe the fix approach at a high level.
+
+### Code Changes
+
+**File:** `path/to/file.{{FILE_EXTENSION}}`
+
+Before:
+```{{FILE_EXTENSION}}
+// Problematic code
+```
+
+After:
+```{{FILE_EXTENSION}}
+// Fixed code
+```
+
+### Additional Changes
+
+- [ ] Database migration required
+- [ ] Configuration change required
+- [ ] Cache invalidation required
+
+## Testing Requirements
+
+### Regression Tests
+
+- [ ] Test that the specific bug is fixed
+- [ ] Test related functionality still works
+- [ ] Test edge cases
+
+### Test Cases
+
+| Test Case                    | Input        | Expected Output       |
+| ---------------------------- | ------------ | --------------------- |
+| Original bug scenario        | X            | Y (fixed behavior)    |
+| Edge case 1                  | A            | B                     |
+| Edge case 2                  | C            | D                     |
+
+## Prevention
+
+### How to Prevent Recurrence
+
+- [ ] Add validation for X
+- [ ] Improve error handling
+- [ ] Add monitoring/alerting
+- [ ] Update documentation
+
+### Process Improvements
+
+- Lesson learned 1
+- Lesson learned 2
+
+## References
+
+- [Issue Tracker]({{ISSUE_TRACKER_URL}})
+- [Related PR](link)
+- [Error Logs](link)
+- [Monitoring Dashboard](link)
+
+---
+
+## Changelog
+
+| Date       | Author     | Change Description        |
+| ---------- | ---------- | ------------------------- |
+| {{DATE}}   | {{AUTHOR}} | Initial investigation     |