Team Knowledge Auto

The Team Knowledge Auto command maps team expertise, identifies knowledge concentration risks, and generates skill gap analyses with targeted learning recommendations. It examines code contribution patterns, review activity, and module ownership to build a comprehensive picture of how knowledge is distributed across the team. Execute this command when you need to understand who knows what, where knowledge gaps exist, and how to distribute expertise more evenly.

When to Use This Command

Run this command when...

• You need to identify bus factor risks where critical modules have only one or two contributors with deep knowledge
• You are planning knowledge transfer activities and need to know which team members should mentor whom on which modules
• You want to understand the team's technology stack expertise to make informed decisions about project assignments
• You are hiring and need to identify which skills are underrepresented on the team for targeted job descriptions
• You want to track knowledge distribution trends over time to verify that cross-training initiatives are producing results

Consider alternatives when...

• You need to plan sprint work based on team capacity, which the sprint planning command handles with workload balancing
• You are analyzing code dependencies rather than human expertise, which the dependency mapper command addresses
• You need individual performance evaluation rather than knowledge mapping, which is outside the scope of development tooling

Quick Start

Copy
# knowledge-mapper.yml
analysis:
  period: "last-3-months"
  sources:
    - git-contributions
    - pr-reviews
    - issue-assignments
  metrics:
    - module-ownership
    - technology-breadth
    - review-expertise
    - bus-factor
knowledge-map:
  modules: "auto-detect"
  technologies: "auto-detect"
  granularity: "directory"
recommendations:
  cross-training: true
  hiring-gaps: true

Example invocation:

Copy
/team-knowledge-auto --period "3-months" --bus-factor --recommendations

Example output:

Team Knowledge Map
====================
Team: Engineering (6 members)
Analysis period: Dec 15, 2025 - Mar 15, 2026

Module Ownership:
  src/lib/auth/      Alice (82%), Bob (18%)         Bus factor: LOW
  src/lib/api/       Bob (45%), Carol (35%), Dave (20%)  Bus factor: OK
  src/lib/store/     Carol (90%), Eve (10%)          Bus factor: LOW
  src/lib/ui/        Dave (30%), Eve (40%), Frank (30%)  Bus factor: OK
  src/routes/        Alice (25%), Bob (25%), Carol (25%), Dave (25%)  Bus factor: GOOD

Technology Expertise:
  TypeScript:   Alice (expert), Bob (advanced), Carol (advanced)
  SvelteKit:    Carol (expert), Dave (advanced), Eve (intermediate)
  PostgreSQL:   Bob (expert), Alice (intermediate)
  Redis:        Bob (intermediate), others (minimal)
  Testing:      Eve (advanced), Frank (advanced)

Bus Factor Risks:
  CRITICAL: src/lib/auth/ - Alice is sole deep expert
  CRITICAL: src/lib/store/ - Carol is sole deep expert
  WARNING: Redis knowledge concentrated in Bob

Recommendations:
  1. Pair Bob with Dave on auth module for 2 sprints
  2. Schedule Carol to mentor Eve on store architecture
  3. Create Redis knowledge-sharing session led by Bob
  4. Consider hiring: Backend engineer with caching/Redis experience

Knowledge trend (vs. last quarter):
  Distribution improved: +15% more cross-module contributions
  New expertise areas: Alice learned testing, Frank started API work

Core Concepts

Concept	Purpose	Details
Contribution Analysis	Map who works where	Examines git blame, commit history, and file ownership to determine which team members have deep knowledge of each module
Bus Factor Calculation	Identify knowledge risks	Computes the minimum number of team members whose absence would stall development of each module
Technology Profiling	Assess skill breadth	Catalogs team members' experience across programming languages, frameworks, databases, and infrastructure tools
Review Expertise	Identify secondary knowledge	Tracks code review activity to find team members who have review-level knowledge of modules they do not primarily contribute to
Learning Recommendations	Guide skill development	Generates specific pairing, mentoring, and training suggestions based on knowledge gaps and team strengths

Architecture: Knowledge Mapping
==================================

+-------------------+     +---------------------+     +------------------+
| Contribution Scan | --> | Ownership Calculator| --> | Bus Factor Engine|
| (git blame, PRs)  |     | (percentage share)  |     | (risk assessment)|
+-------------------+     +---------------------+     +------------------+
                                                             |
                          +----------------------------------+
                          v
              +---------------------+     +-------------------+
              | Skill Profiler      | --> | Recommendation Gen|
              | (technology matrix) |     | (training plan)   |
              +---------------------+     +-------------------+

Configuration

Parameter	Type	Default	Description
period	string	"3-months"	Time period to analyze for contribution and expertise data
bus-factor	boolean	true	Calculate and report bus factor risks for each module
recommendations	boolean	true	Generate cross-training and hiring recommendations based on knowledge gaps
granularity	string	"directory"	Analysis granularity: directory for module-level, file for file-level, or function for fine-grained mapping
trend	boolean	false	Compare current knowledge distribution against a previous period to show improvement trends

Best Practices

1. Run knowledge mapping quarterly to track distribution trends. Monthly analysis is too frequent to show meaningful change; annual analysis misses important shifts. Quarterly mapping provides enough data to show trends while giving cross-training initiatives time to produce measurable results.

2. Act on bus factor risks before they become crises. When the analysis identifies a critical module with a single knowledgeable contributor, schedule pair programming or code walkthrough sessions within the next sprint. Waiting for the contributor to go on vacation before addressing the risk converts a manageable situation into an urgent one.

3. Use review expertise as a leading indicator of knowledge spread. Team members who review code for a module develop secondary expertise that can grow into primary ownership. Encourage review participation across modules as a low-cost way to spread knowledge before investing in dedicated mentoring sessions.

4. Include technology expertise in hiring decisions. When the skill matrix reveals that a critical technology like database administration or infrastructure management has minimal team coverage, incorporate that skill into your next hire's requirements rather than hoping existing team members will develop it organically.

5. Celebrate knowledge distribution improvements. When quarterly comparisons show that bus factor risks have been reduced and cross-module contributions have increased, acknowledge the team's investment in knowledge sharing. Positive reinforcement encourages continued participation in cross-training activities.

Common Issues

Contribution metrics underrepresent pair programming. When two developers pair on a task, only one person's name appears in the commit author field. Use co-author trailer attribution or manually adjust ownership percentages to reflect the actual knowledge gained through pairing sessions.

Module boundaries do not align with knowledge boundaries. Directory-based module detection may split logically related code across multiple directories or group unrelated code together. Customize the module definition to match your project's actual architectural boundaries for more meaningful ownership analysis.

Historical data insufficient for new team members. Developers who recently joined the team have minimal contribution history, causing the analysis to underrepresent their expertise. Supplement contribution-based analysis with self-reported skill assessments for new team members until they have accumulated sufficient contribution history.