Skip to content

Commit b8cf597

Browse files
author
Kristopher Turner
committed
chore: add project management files for implementation standardization
- Implementation standardization plan with decisions and phases - Full tracking log with audit results for all 137+ task files - Discovery report with gap analysis (docs vs toolkit scripts) - Task page standard template (canonical format for all task pages) - Phase index page standard template
1 parent fb8d7df commit b8cf597

5 files changed

Lines changed: 1275 additions & 0 deletions

File tree

‎project-management/claude/discovery-report.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Discovery Report — Implementation Docs & Toolkit Alignment
2+
3+
> Generated: 2026-03-24
4+
> Based on: Full audit of docs/implementation/ (201 files) and scripts/deploy/ (200+ scripts)
5+
6+
## Summary
7+
8+
The implementation docs span 8 parts with ~137 task pages. The azurelocal-toolkit has ~200 PowerShell scripts organized to mirror the docs structure. Parts 1-5 have mostly good content but inconsistent formatting. Parts 6-8 have thin content and almost no scripts.
9+
10+
## Docs Repo Structure (azurelocal.github.io)
11+
12+
```
13+
docs/implementation/
14+
├── 01-cicd-infrastructure/ 6 tasks, 1 phase
15+
├── 02-azure-foundation/ 30+ tasks, 5 phases
16+
├── 03-onprem-readiness/ 12 tasks, 3 phases
17+
├── 04-cluster-deployment/ 37 tasks, 6 phases
18+
├── 05-operational-foundations/ 21 tasks, 5 phases
19+
├── 06-testing-validation/ 6 tasks, no phases
20+
├── 07-validation-handover/ 7 tasks, 2 phases
21+
├── 08-lifecycle-operations/ 3 docs
22+
└── appendices/ 15 files
23+
```
24+
25+
## Toolkit Repo Structure (azurelocal-toolkit)
26+
27+
```
28+
scripts/deploy/
29+
├── 01-cicd-automation/
30+
├── 02-azure-foundation/
31+
├── 03-on-prem-readiness/
32+
├── 04-cluster-deployment/
33+
├── 05-operational-foundations/
34+
├── 06-testing-validation/
35+
├── 07-validation-handover/
36+
└── (08 lifecycle lives in scripts/lifecycle/)
37+
```
38+
39+
## Format Compliance Matrix
40+
41+
### Reference Examples (Gold Standard)
42+
43+
| File | Score | Notes |
44+
|------|-------|-------|
45+
| 04/phase-01/task-01-dhcp-reservations | 🟢 Full | All sections present — best task reference |
46+
| 02/phase-02/task-01-register-providers | 🟢 Full | All sections present — best Azure task reference |
47+
| 04/phase-01/index.mdx | 🟢 Full | Best phase index reference |
48+
| 02/phase-02/index.mdx | 🟢 Full | Alternative phase index style |
49+
50+
### Format Deviation Patterns
51+
52+
| Pattern | Affected Files (approx) |
53+
|---------|------------------------|
54+
| Missing full frontmatter (only 4 fields) | ~30 files (mostly Parts 5-8) |
55+
| Missing metadata blockquote | ~25 files |
56+
| Missing Variables Used table | ~40 files |
57+
| Missing Troubleshooting table | ~35 files |
58+
| Missing Validation Checklist | ~20 files |
59+
| Missing Version Control section | ~30 files |
60+
| Wrong/missing tab groupId | ~10 files |
61+
| Tab labels non-standard | ~15 files |
62+
| No tabs at all (inline code) | ~16 files (Parts 6-8) |
63+
64+
## Script Alignment Gaps
65+
66+
### Critical Gaps (Docs exist, scripts missing)
67+
68+
| Part/Phase | Tasks | Gap Type | Priority |
69+
|------------|-------|----------|----------|
70+
| 03/phase-01 (Active Directory) | tasks 02-05 | No scripts | High |
71+
| 04/phase-01 (Hardware) | tasks 01,03,04,05 | Empty folders (.gitkeep) | High |
72+
| 04/phase-06 (Post-Deployment) | ALL 8 tasks | 0 scripts in deploy/ | Critical |
73+
| 05/phase-02 (Monitoring) | task-03 HCI Insights | Missing | Medium |
74+
| 05/phase-03 (Backup/DR) | task-02 Site Recovery | Missing | Medium |
75+
| 05/phase-04 (Security) | tasks 01,04,05 | Missing | Medium |
76+
| 05/phase-05 (Licensing) | task-01 Hybrid Benefit | Missing | Medium |
77+
| 06 (Testing) | ALL 6 tasks | 0 scripts | High |
78+
| 07 (Go-Live) | ALL 7 tasks | 0 scripts | High |
79+
| 08 (Lifecycle) | ALL 3 docs | No deploy scripts | Medium |
80+
81+
### Well-Aligned Areas (No Gaps)
82+
83+
| Part/Phase | Tasks | Alignment |
84+
|------------|-------|-----------|
85+
| 04/phase-03 (OS Configuration) | 13/13 | 100% ✓ |
86+
| 04/phase-04 (Arc Registration) | 4/4 | 100% ✓ |
87+
| 03/phase-02 (Enterprise Readiness) | 4/4 | 100% ✓ |
88+
| 03/phase-03 (Network Infrastructure) | 4/4 | 100% ✓ |
89+
| 05/phase-01 (SDN Deployment) | 3/3 | 100% ✓ |
90+
91+
### Partial Alignment
92+
93+
| Part/Phase | Aligned | Total | Notes |
94+
|------------|---------|-------|-------|
95+
| 02/phase-04 (Mgmt Infra) | 13 | 15 | Missing P2S VPN, mgmt VMs |
96+
| 05/phase-02 (Monitoring) | 6 | 7 | Missing HCI Insights |
97+
98+
## Tab Standard Deviations Found
99+
100+
| File Pattern | Current Tab Labels | Should Be |
101+
|-------------|-------------------|-----------|
102+
| 04/phase-01/task-01 | FortiGate / Windows / Customer (device-type) | Approved override ✓ |
103+
| 04/phase-03/* | Direct / Orchestrated | Manual (RDP/Console) / Orchestrated / Standalone |
104+
| 01-cicd/* | GitHub / GitLab / Azure DevOps (platform) | Approved override ✓ |
105+
| 02/phase-02/task-01 | Azure Portal / Azure CLI PowerShell / Standalone | Portal label OK, CLI label needs fix |
106+
107+
## Approved Tab GroupId Overrides
108+
109+
These contexts justify a non-standard groupId or tab 1 label:
110+
111+
| GroupId | Tab 1 Label | Context |
112+
|---------|-------------|---------|
113+
| `device-type` | FortiGate DHCP / Windows DHCP / Customer | Hardware-specific DHCP tasks |
114+
| `platform` | GitHub / GitLab / Azure DevOps | CI/CD pipeline tasks |
115+
116+
All other tasks should use `groupId="deployment-method"`.
117+
118+
## Content Quality Assessment
119+
120+
| Part | Content Quality | Format Quality | Scripts | Overall |
121+
|------|----------------|----------------|---------|---------|
122+
| 1 — CI/CD | Good | Medium | N/A | 🟡 |
123+
| 2 — Azure Foundation | Good | Good (recently updated) | Mostly aligned | 🟢 |
124+
| 3 — On-Prem Readiness | Good | Medium | Partial gaps | 🟡 |
125+
| 4 — Cluster Deployment | Good | Variable | Phase-06 critical gap | 🟡 |
126+
| 5 — Operational | Medium | Low-Medium | Multiple gaps | 🟡 |
127+
| 6 — Testing | Poor (thin) | Poor (no standard format) | None | 🔴 |
128+
| 7 — Go-Live | Poor (thin) | Poor | None | 🔴 |
129+
| 8 — Lifecycle | Poor (thin) | Poor | None | 🔴 |

‎project-management/claude/implementation-standardization-plan.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Plan: Implementation Docs & Toolkit Standardization
2+
3+
> Project start: 2026-03-24
4+
> Status: **In Progress**
5+
6+
## TL;DR
7+
8+
Standardize ~137 task pages across the implementation docs (azurelocal.github.io) and align ~200 toolkit scripts (azurelocal-toolkit) to match. Create a documented page standard, fix formatting across Parts 1-5, create deep content for Parts 6-8, and ensure every doc task has corresponding scripts in the toolkit.
9+
10+
## Decisions (Confirmed)
11+
12+
| Decision | Value |
13+
|----------|-------|
14+
| Azure primary script | Azure PowerShell (Az module) |
15+
| On-prem primary script | PowerShell 7 (pwsh) |
16+
| Alternate script | Azure CLI for PowerShell (az commands in .ps1) — appendix/alternate tab only |
17+
| Azure task tabs | `Azure Portal` \| `Orchestrated Script` \| `Standalone Script` (groupId="deployment-method") |
18+
| On-prem task tabs | `Manual (RDP/Console)` \| `Orchestrated Script` \| `Standalone Script` (groupId="deployment-method") |
19+
| Context-specific tab 1 | When task targets specific hardware/software, tab 1 label adapts but groupId stays "deployment-method" |
20+
| Backup branches | `backup/implementation-standardization-20260324` in both repos |
21+
| Priority | Parts 1-5 format alignment + toolkit sync FIRST, then Parts 6-8 content |
22+
| Example company | Infinite Azure Local Corp (IIC), eastus region |
23+
| Author | Azure Local Cloudnology Team |
24+
25+
## Phases
26+
27+
### Phase 0: Setup & Standards
28+
29+
- [x] 0.1 Create backup branches in both repos
30+
- [x] 0.2 Create project-management/claude/ folder with plan, tracking, discovery, standards
31+
- [x] 0.3 Create Task Page Standard template
32+
- [x] 0.4 Create Phase Index Page Standard template
33+
34+
### Phase 1: Audit & Gap Analysis
35+
36+
- [ ] 1.1 Generate complete alignment matrix (doc vs toolkit per task)
37+
- [ ] 1.2 Identify formatting deviations from standard across Parts 1-5
38+
- [ ] 1.3 Identify content gaps in Parts 6-8
39+
40+
### Phase 2: Parts 1-5 Format Standardization
41+
42+
- [ ] 2.1 Part 1: CI/CD Infrastructure (6 tasks)
43+
- [ ] 2.2 Part 2: Azure Foundation (30+ tasks, 5 phases)
44+
- [ ] 2.3 Part 3: On-Prem Readiness (12 tasks, 3 phases)
45+
- [ ] 2.4 Part 4: Cluster Deployment (37 tasks, 6 phases)
46+
- [ ] 2.5 Part 5: Operational Foundations (21 tasks, 5 phases)
47+
48+
### Phase 3: Parts 6-8 Content Creation
49+
50+
- [ ] 3.1 Part 6: Testing & Validation (6 tasks) — deep content + scripts
51+
- [ ] 3.2 Part 7: Go-Live (7 tasks, 2 phases) — verification + handover
52+
- [ ] 3.3 Part 8: Lifecycle Operations (3 docs) — complete content creation
53+
54+
### Phase 4: Appendices Update
55+
56+
- [ ] 4.1 Update appendix-d-script-index.mdx
57+
- [ ] 4.2 Review other appendices for format consistency
58+
59+
### Phase 5: Toolkit Script Creation
60+
61+
- [ ] 5.1 Create missing scripts for documented tasks (see gap analysis)
62+
- [ ] 5.2 Relocate misplaced scripts (04/phase-06 post-deployment)
63+
64+
### Phase 6: Content Verification
65+
66+
- [ ] 6.1 Verify Azure content against current Microsoft docs
67+
- [ ] 6.2 Verify on-prem content (Dell, Windows Server, AD)
68+
- [ ] 6.3 Run Docusaurus build to catch broken links
69+
70+
## Script Gap Summary
71+
72+
| Area | Gap |
73+
|------|-----|
74+
| 03/phase-01 AD tasks 02-05 | Docs exist, no scripts |
75+
| 04/phase-01 tasks 01,03,04,05 | Empty script folders (.gitkeep only) |
76+
| 04/phase-06 ALL 8 tasks | Docs exist, 0 scripts in deploy folder |
77+
| 05 scattered | ~7 tasks missing scripts |
78+
| 06 ALL 6 tasks | Thin docs + 0 scripts |
79+
| 07 ALL 7 tasks | 0 scripts |
80+
| 08 ALL 3 docs | Thin content, no scripts |
81+
82+
## Well-Aligned Areas (No Script Gaps)
83+
84+
- 04/phase-03-os-configuration: 13/13 tasks ✓
85+
- 04/phase-04-arc-registration: 4/4 tasks ✓
86+
- 03/phase-02-enterprise-readiness: 4/4 tasks ✓
87+
- 03/phase-03-network-infrastructure: 4/4 tasks ✓
88+
- 05/phase-01-sdn-deployment: 3/3 tasks ✓

0 commit comments

Comments
 (0)