Orchestrator/bahn/project-audit/rules.md

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)