Product Documentation Modernization Skill

Version: 1.0.0 Created: 2026-01-08 Category: Documentation, Product Management, Standards Compliance

Overview

This skill provides a systematic approach to reviewing and modernizing Agent OS product documentation (mission.md, tech-stack.md, roadmap.md) to ensure quantifiable value propositions, workspace-hub standards compliance, and engineering-specific differentiation.

When to Use

Use this skill when:

• Initializing Agent OS product documentation for new repositories

• Reviewing existing product documentation for improvements

• Ensuring compliance with workspace-hub standards (UV, Plotly, file organization)

• Adding quantifiable metrics and success criteria to product documents

• Modernizing technology stacks to current best practices

• Documenting modular architecture decisions

Skill Components

1. Mission Document Review & Enhancement

Checklist for mission.md:

Pitch Section:

• Includes quantifiable claim (e.g., "reduces overhead by 70%")

• Clearly states target users and specific pain point

• Explains value proposition in one sentence

• Uses active, benefit-focused language

User Personas:

• Includes age range and role

• Defines business context (number of projects, team size, etc.)

• Lists specific, measurable pain points with time/cost impacts

• States concrete goals with success criteria

Example:

Business Administrator (28-45 years old)

• Role: Administrative Manager or Business Operations Coordinator
• Context: Day-to-day management of business finances, invoicing, and compliance for 3-7 concurrent engineering projects
• Pain Points:
  • Spending 6-8 hours/week on invoice generation across multiple clients
  • Manual expense categorization from credit card statements (2-3 hours/week)
  • Annual tax preparation requires 20-30 hours of document organization
• Goals:
  • Reduce administrative time by 70% to focus on business development
  • Achieve 100% on-time invoice delivery (currently 75%)

Key Features:

• Each feature includes impact metrics or time savings

• Features grouped by category (Core, Collaboration, Integration)

• Features written from user benefit perspective, not technical implementation

Success Metrics Section (Required):

• Efficiency Gains: Specific time reductions (e.g., 85% reduction in invoice time)

• Business Impact: Dollar savings (e.g., $15K-25K annually)

• Adoption Success: Timeline and satisfaction metrics

• All metrics are measurable and achievable

Implementation Approach Section (Required):

• Phased approach with clear timelines

• Each phase shows immediate value delivery

• Zero business disruption strategy

• Manual override availability

2. Tech Stack Modernization

Checklist for tech-stack.md:

Core Technologies:

• Uses UV package manager (workspace-hub standard) - NOT Conda/Poetry

• Python 3.11+ specified with modern type hints

• All dependencies use current major versions (e.g., Pandas 2.0+, not 1.x)

• Deprecated libraries replaced (e.g., pypdf instead of PyPDF2)

Visualization Standards:

• Plotly MANDATORY for all visualizations

• Explicit note: "All visualizations MUST be interactive (Plotly)"

• NO Matplotlib, seaborn, or static image exports

• Kaleido for static exports FROM interactive Plotly charts only

Modular Architecture:

• Reflects decisions.md modular design (e.g., DEC-003)

• Each module has clear CLI command (e.g., invoice-gen , tax-prep )

• Shared components explicitly listed

• Module boundaries clearly defined

Complete Dependencies:

• Full pyproject.toml configuration included

• All categories covered: data processing, document generation, visualization, email, automation, logging, CLI, testing

• Development dependencies separated ([project.optional-dependencies] )

• Entry point scripts defined ([project.scripts] )

CLI Interface:

• Click or Typer framework specified

• Command examples for each module

• Option documentation included

• Usage patterns demonstrated

Testing Strategy:

• Coverage requirements specified (minimum 80%, critical modules 95%)

• Test structure documented (unit/, integration/, performance/)

• Testing commands provided

Development Environment:

• UV installation instructions

• Virtual environment creation steps

• Cross-platform support (Windows/macOS/Linux)

• Editor recommendations

3. Standards Compliance Verification

Workspace-Hub Standards:

UV Package Manager:

✅ Correct

uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e .

❌ Wrong

conda create -n myenv pip install -r requirements.txt

Interactive Visualizations:

✅ Correct - Plotly interactive

import plotly.express as px fig = px.scatter(df, x='time', y='value') fig.write_html('../reports/analysis.html')

❌ Wrong - Matplotlib static

import matplotlib.pyplot as plt plt.scatter(df['time'], df['value']) plt.savefig('plot.png')

File Organization:

• Reports in /reports/ directory

• Data in /data/ (raw/, processed/, results/)

• No files saved to root folder

• Module-based source organization in /src/

CSV Data Import:

• Uses relative paths from report location

• No hardcoded absolute paths

• Standardized data directory structure

4. Quantification Framework

Adding Metrics to Documents:

Time Savings Calculation:

Before: 15 minutes per invoice × 10 invoices/month = 150 minutes/month After: 2 minutes per invoice × 10 invoices/month = 20 minutes/month Reduction: 130 minutes/month = 87% time savings

Cost Savings Calculation:

Hourly rate: $75/hour Time saved: 130 minutes/month × 12 months = 1,560 minutes/year = 26 hours/year Value: 26 hours × $75 = $1,950/year per use case

Total across 3 use cases: ~$5,850/year Add accountant fee reduction: $2,000-5,000/year Total: $15,000-25,000/year

Adoption Timeline:

Week 1-2: Initial setup and first automated invoice Week 3-4: Expense tracking automation Week 5-8: Full tax preparation integration Result: 8 weeks to full adoption

5. Engineering-Specific Differentiation

For Engineering Firms:

• Project-based billing emphasized

• Technical hours tracking mentioned

• Multi-client parallel project management

• Engineering service-specific expense categories (certifications, software licenses, standards)

• Professional engineering compliance tracking

Example Differentiator:

Engineering Project Financial Tracking

Unlike generic accounting systems, we provide project-based billing with technical hours tracking, multi-client parallel project management, and engineering service-specific expense categorization (design software, certifications, industry standards). This results in accurate project profitability analysis and improved resource allocation for engineering teams.

Implementation Process

Step 1: Read Current Documentation

Read all three product documents

cat .agent-os/product/mission.md cat .agent-os/product/tech-stack.md cat .agent-os/product/decisions.md

Step 2: Review Against Standards

• Compare against workspace-hub standards

• Check for deprecated technologies

• Verify quantifiable metrics exist

• Ensure modular architecture documented

Step 3: Suggest Improvements

• Organize suggestions by category

• Prioritize based on impact

• Provide specific examples

• Include rationale for each change

Step 4: Implement Changes

• Use Edit operations for precision

• Update version numbers and dates

• Maintain document structure

• Cross-reference with decisions.md

Step 5: Validate Compliance

• Verify UV package manager used

• Confirm Plotly for all visualizations

• Check modular architecture alignment

• Ensure quantifiable metrics included

Templates

Mission.md Success Metrics Template

Success Metrics

Efficiency Gains

• [Feature]: [%] reduction in time ([before] → [after])
• [Feature]: [%] reduction in [metric] ([before] → [after])

Business Impact

• Cost Savings: $[amount] annually ([breakdown])
• Revenue Protection: $[amount] in [area]
• Risk Reduction: [%] accuracy improvement

Adoption Success

• Time to First Value: [timeframe]
• Full System Adoption: [timeframe]
• User Satisfaction: [measurable outcome]

Tech-Stack.md pyproject.toml Template

[project] name = "project-name" version = "1.0.0" description = "Brief description" requires-python = ">=3.11" dependencies = [ # Data Processing "pandas>=2.0.0", "numpy>=1.24.0",

# Visualization (Interactive Only)
"plotly>=5.14.0",
"kaleido>=0.2.1",

# CLI Development
"click>=8.1.0",

]

[project.optional-dependencies] dev = [ "pytest>=7.4.0", "pytest-cov>=4.1.0", "ruff>=0.1.0", ]

[project.scripts] module-name = "package.module:main"

Example Usage

Review Mission Document

In Claude Code or AI agent

"Review the mission.md file and suggest improvements following the Product Documentation Modernization skill. Focus on adding quantifiable metrics and engineering-specific value propositions."

Modernize Tech Stack

In Claude Code or AI agent

"Review tech-stack.md for compliance with workspace-hub standards. Replace Conda with UV, ensure Plotly is mandatory, and add complete pyproject.toml configuration."

Success Criteria

Documentation is successfully modernized when:

Mission.md:

• Includes 3+ quantifiable efficiency gains

• Contains dollar-value business impact metrics

• Has complete Success Metrics section

• Includes Implementation Approach section

• Features engineering-specific differentiation

Tech-stack.md:

• Uses UV package manager (not Conda)

• Plotly mandatory with explicit note

• Complete pyproject.toml included

• Modular architecture documented

• CLI commands for all modules

• Testing strategy with coverage requirements

• Development environment setup included

Both Documents:

• Version updated (e.g., 1.0.0 → 2.0.0)

• Date updated to current

• Cross-referenced with decisions.md

• No deprecated technologies

• No workspace-hub standard violations

Related Skills

• File Organization Skill - For organizing documentation and code files

• Standards Compliance Skill - For verifying workspace-hub standards

• Quantification Skill - For calculating time and cost savings

• Agent OS Initialization Skill - For setting up new repositories

References

• Workspace-Hub Standards: @/mnt/github/workspace-hub/docs/modules/standards/

• Agent OS Instructions: @~/.agent-os/instructions/

• UV Package Manager: https://github.com/astral-sh/uv

• Plotly Documentation: https://plotly.com/python/

Version History

• 1.0.0 (2026-01-08): Initial skill creation based on aceengineer-admin mission.md and tech-stack.md modernization work