# Project Portfolio Audit — Rules & Methodology

## Working Rules

> *To be refined after interview*

### Data Handling

1. **Iterative deepening** — We don't try to analyze everything at once. Each pass focuses on a specific dimension or subset.
2. **Condense before expanding** — After each analysis pass, we summarize findings before moving to the next area.
3. **Source of truth hierarchy** — Code > Confluence docs > tribal knowledge. When conflicts arise, code wins.
4. **Tag everything** — Every finding gets tagged with: project, severity, category, and effort estimate.
5. **All deliverables in German** — Documentation, analysis, roadmap, slides — alles auf Deutsch.
6. **Audience-aware writing** — First audience: Management Board. Later: Architects, Product Owners, then Dev Teams.
7. **Time tracking** — Record effort per task to improve estimation for future iterations.

### Analysis Categories

- **Fachliche Architektur** — Domain model, business workflows, bounded contexts, fachliche Schnittstellen
- **Technische Architektur** — Service boundaries, dependencies, data flows, deployment topology
- **Code Quality** — Tech debt, complexity, test coverage, code smells
- **Security** — Vulnerabilities, outdated dependencies, secrets management
- **Documentation** — Accuracy, completeness, staleness
- **Operations** — CI/CD maturity, deployment process, monitoring, logging, alerting
- **Dependencies** — Inter-project dependencies, external library health
- **Team Topology** — Current team structure, ownership mapping, workflow analysis

### Deliverable Standards

1. Every analysis produces a structured markdown document.
2. Architectural views use Mermaid diagrams where possible.
3. Findings are rated: **Critical / High / Medium / Low / Info**
4. Actionable items follow the format: `[Priority] [Effort] Description → Expected Outcome`

### Iteration Protocol

1. **Scope an iteration** — Define what we're looking at and why.
2. **Gather** — Pull in relevant data (code, docs, configs).
3. **Analyze** — Apply the relevant analysis lens.
4. **Document** — Write up findings in structured format.
5. **Condense** — Summarize key takeaways.
6. **Decide** — Determine what to explore next based on findings.

## Naming Conventions

- Directories: `kebab-case`
- Analysis files: `{project-name}-analysis.md`
- Summary files: `{category}-summary.md`
- Iteration logs: `iteration-{nn}-{focus}.md`

## Quality Gates

- [ ] Each iteration produces a condensed summary readable by Management Board
- [ ] Technical deep dives are clearly separated from management overviews
- [ ] Every analysis links back to source (GitLab project, Confluence page, or code reference)
- [ ] Roadmap items have effort estimates informed by tracked time data

## Known Pain Points (from Interview)

1. **Deployment** — Very time-consuming process, needs investigation
2. **No clear architectural view** — No existing abstraction layer for understanding the system
3. **Development speed** — Underwhelming, needs to increase to match customer pressure
4. **Team structure** — Regrouping planned; needs understanding of current team-to-project mapping
5. **Lack of overview** — No management-ready abstraction of ongoing development

## Iteration Roadmap (High-Level Phases)

### Phase 1: Domain Understanding (Fachliche Architektur)
- Collect and consolidate domain knowledge from public sources and Confluence
- Build domain model, glossary, and business workflow maps
- Iterative: start broad, deepen per domain area

### Phase 2: Technical Crunch (Technische Architektur)
- Inventory all ~140 GitLab projects
- Map technical architecture, service dependencies, data flows
- Identify code quality issues and tech debt hotspots

### Phase 3: Team & Workflow Analysis
- Map current team structure to projects/domains
- Analyze development workflows and bottlenecks
- Propose team regrouping based on domain and technical boundaries

### Phase 4: Roadmap & Action Plan
- Synthesize findings into prioritized action items
- Create management-ready roadmap with effort estimates
- Deliver in Confluence homepage format (or slides as fallback)