gh-bradleyboehmke-brads-marketplace-document-generator/commands/update-readme.md

description

description
Refactor existing README.md to conform to standards

Update README

Activated Agent

Activate: readme-author agent

The agent will refactor your existing README.md to meet Personal minimal standards.

Objective

Update existing README.md to conform to 8-section minimal structure, preserving compliant content while adding missing sections and integrating business context.

Command Parameters

Parameter	Options	Default	Description
--sections	Comma-separated: title, badges, description, installation, documentation, components, contributing, bugs	All missing/incomplete	Specific sections to update
--tier	prototype, mvp, production	Auto-detect	Target project tier
--format	console, markdown	console	Output format (console display vs. write file)
--output	<path>	./README.md	Output path (use different path to preserve original)
--interactive	true, false	true	Show diffs and prompt for approval

Examples:

/document-generator:update-readme                                      # Interactive, all sections
/document-generator:update-readme --sections=description,documentation
/document-generator:update-readme --tier=mvp --format=markdown --interactive=false
/document-generator:update-readme --output=./README-new.md --format=markdown

Activated Skills

The agent will activate these skills:

1. readme-authoring - Templates for missing sections
2. readme-standards - Validation criteria and compliance checking

Process

The agent will follow this workflow:

1. Pre-flight Checks

Check if README.md exists:

• If README.md not found:

  ❌ No README.md found in current directory.
  
  Use `/document-generator:generate-readme` to create one.
  
  Aborting update.
  

  • Stop execution

Create backup (before making changes):

cp README.md README.md.backup

Notify user:

📁 Backup created: README.md.backup

2. Validate Current README

Run validation first (same logic as validate-readme):

• Parse structure
• Identify missing/incomplete sections
• Check content quality
• Validate links

Display current state:

📊 Current README Status

Tier: MVP (detected)
Compliance: ✅ Minimal

Issues found:
⚠️  1. Short Description - Missing business problem context
⚠️  2. Documentation - ADRs not linked (adr/ exists)
❌ 3. Contributing - Section missing
ℹ️  4. Badges - Not present (recommended for MVP tier)

Ready to fix these issues.

3. Determine Sections to Update

If --sections parameter provided:

• Only update specified sections
• Skip sections not in the list

If no --sections parameter:

• Update all missing sections (❌)
• Update all incomplete sections (⚠️)
• Note optional sections (ℹ️) but don't auto-add unless requested

Priority order:

1. Missing required sections (Contributing, Installation, etc.)
2. Incomplete sections (missing business context, broken links)
3. Optional enhancements (Badges, Supporting Components)

4. Extract Context for Updates

Same extraction logic as generate-readme:

For missing/incomplete sections, gather:

• Project metadata (from pyproject.toml, package.json, etc.)
• Business context (from docs, code, or user input)
• Existing documentation to link
• Issue tracker URL
• CONTRIBUTING.md location

Preserve existing content:

• Don't regenerate compliant sections
• Extract and reuse content from non-compliant sections
• Maintain user's formatting choices where possible

5. Generate Section Updates

For each section needing update:

Title & One-Liner:

• Preserve existing title if present
• Add one-liner if missing
• Improve vague descriptions

Badges (if missing and tier >= MVP):

• Generate minimal badge set
• Insert after title, before description

Short Description:

• If "## Overview" exists instead of "## Description":

  • Keep as "## Overview" (both acceptable per standards)
  • Only update if content lacks business context

• If separate "Business Problem" and "Solution" sections exist:

  • Note: This is acceptable per flexible standards
  • Offer to merge into single ## Description or ## Overview paragraph for conciseness (optional)
  • If user prefers merged format: Extract, merge, show diff
  • If user prefers separate: Keep as-is if content is brief and focused

• If description/overview lacks business context:

  • Prompt user for business problem/solution
  • Integrate into existing description or overview
  • Preserve technical details

Installation:

• If missing: Generate from project type
• If incomplete: Add link to setup guide if exists
• If overly detailed: Suggest moving to docs/setup.md

Documentation:

• Check if docs are in dedicated ## Documentation section OR within ## Guides or similar
• Add links to discovered docs not currently linked (anywhere in README)
• If docs scattered across multiple sections, offer to consolidate (optional)
• Verify all existing links still valid
• Organize in logical order (Quickstart, API, Architecture, ADRs)

Supporting Components:

• Only add if dependencies detected
• Skip if standalone project

Contributing:

• Check if contributing link exists in dedicated ## Contributing section OR within ## Documentation/## Guides
• If CONTRIBUTING.md exists but not linked anywhere: Add link (in existing docs section or create new Contributing section)
• If no CONTRIBUTING.md: Offer to create basic Contributing section with inline guidance
• Add test command if detectable

Issue Reporting:

• Check if issue reporting exists in dedicated ## Bugs section OR within ## Contributing/## Documentation
• If missing anywhere: Add link (in existing section or create new Bugs section)
• GitHub Issues link if GitHub repo detected
• Prompt user for issue tracker if not detectable

6. Present Diffs (Interactive Mode)

For each section being updated, show before/after diff:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UPDATE: Short Description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

BEFORE:
────────────────────────────────────────────────
## Business Problem
Marketing teams struggle with customer segmentation.

## Solution
This tool provides automated clustering.

## Description
The Customer Segmentation Engine uses ML to group customers.
────────────────────────────────────────────────

AFTER:
────────────────────────────────────────────────
## Description

Marketing teams struggle with customer segmentation, leading to ineffective campaign targeting and low conversion rates. This tool provides automated clustering capabilities using machine learning to group customers by purchasing behavior. The Customer Segmentation Engine processes transaction history and demographic data to generate actionable segments for targeted marketing campaigns.
────────────────────────────────────────────────

Changes:
- Merged Business Problem and Solution sections into Description
- Integrated business context into cohesive paragraph
- Preserved technical details from original Description

Apply this update? (y/n/edit):

User options:

• y: Apply this update
• n: Skip this update
• edit: Modify the generated content before applying
• all: Apply all remaining updates without prompting

If user chooses "edit":

Enter updated content for Short Description:
(Paste content, then press Ctrl+D or type 'done' on new line)

> ___

Accept user's edited content and continue.

7. Apply Updates

Build updated README:

1. Start with existing README content

2. For each section to update:

   • If section exists: Replace content
   • If section missing: Insert in correct position (maintain 8-section order)
   • If section needs removal (e.g., separate Business Problem): Remove it

3. Maintain proper structure:

   • Title first (#)
   • Badges after title (if present)
   • Sections in order (##)
   • Preserve custom sections not in standard 8 (at end)

Example transformation:

Before (non-compliant):

# My Project

## Business Problem
Teams have issues.

## Solution
This fixes it.

## Setup
Install stuff.

After (compliant):

# My Project

Brief description of what this does and why.

## Description

Teams struggle with X problem, leading to Y consequence. This project provides Z solution by implementing W approach. The system handles A, B, and C use cases.

## Installation

\`\`\`bash
pip install my-project
\`\`\`

## Documentation

- [Architecture](docs/architecture.md) - System design
- [ADRs](adr/) - Key decisions

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Bugs & Enhancements

Report issues via [GitHub Issues](https://github.com/org/my-project/issues).

8. Write Updated README

If --format=markdown (write file):

# Write updated README
cat > ./README.md <<'EOF'
{updated content}
EOF

Confirm success:

✓ README.md updated successfully

Sections updated:
  1. Short Description - Merged Business Problem/Solution, added context
  2. Documentation - Added links to ADRs and architecture docs
  3. Contributing - Added link to CONTRIBUTING.md

Backup saved to: README.md.backup

Next steps:
- Review the updated README
- Run `/document-generator:validate-readme` to verify compliance
- Consider creating suggested documentation:
  - docs/quickstart.md

If --format=console (display only):

• Show full updated README
• Don't write file
• Note that backup was NOT created (no changes made)

9. Cleanup

If changes were successfully applied:

• Keep backup file (README.md.backup)
• User can delete backup later

If user cancelled:

• Remove backup file
• Leave original README unchanged

Interactive Patterns

Prompt for Business Context

If description lacks business problem/solution:

The Short Description section is missing business context.

To update it, I need to know:

1. What business problem does this project solve?
   (1-2 sentences describing the problem and its impact)

   > ___

2. What solution does this project provide?
   (1-2 sentences describing how it addresses the problem)

   > ___

Confirm Major Changes

For significant restructuring (merging sections, removing content):

⚠️  Major Restructure Detected

This update will:
- Merge "Business Problem" and "Solution" sections into "Description"
- Remove separate sections (content will be preserved)
- Add 2 new sections (Contributing, Bugs & Enhancements)

This is a significant change. Continue? (y/n):

Handle Custom Sections

If README has custom sections beyond the standard 8:

ℹ️  Custom Sections Detected

Your README contains custom sections:
- ## FAQ
- ## Troubleshooting
- ## Changelog

These will be preserved at the end of the README.

Continue? (y/n):

Constraints

• Preserve compliant content - Don't regenerate sections that meet standards
• Maintain user intent - Keep custom sections, preserve formatting preferences
• Show diffs for transparency - User should see all changes before applying
• Create backups - Always backup before modifying
• Link validation - Only add links to docs that actually exist
• Respect tier - Apply tier-appropriate standards

Error Handling

README.md not found:

• Suggest using generate-readme
• Stop execution

README.md not writable:

• Check file permissions
• Suggest alternative output path

Backup creation fails:

• Warn user
• Prompt to continue without backup or cancel

User cancels mid-update:

• Restore from backup
• Clean up partial changes

Success Criteria

Updated README should:

• ✅ Preserve all compliant existing content
• ✅ Fix identified compliance issues
• ✅ Integrate business context into Description
• ✅ Link to all discovered documentation
• ✅ Follow 8-section minimal structure
• ✅ Pass validation via /document-generator:validate-readme

Special Cases

Optional: Merging Business Problem/Solution Sections

Note: Per updated standards, separate Business Problem/Solution sections are acceptable if brief and focused.

If README has separate sections and user prefers merged format:

## Business Problem
{problem text}

## Solution
{solution text}

## Description
{technical details}

Offer to transform to (optional):

## Description

{problem text}. {solution text}. {technical details}.

Or keep as-is if user prefers separate sections (compliant per flexible standards)

Handling Overly Detailed Installation

If Installation section has:

## Installation

1. Install Python 3.9+
2. Create virtual environment
3. Install dependencies: pip install -r requirements.txt
4. Set up database: ...
5. Run migrations: ...
6. Configure environment: ...

Suggest:

⚠️  Installation section is overly detailed.

Recommendation: Move detailed setup to docs/setup.md

Updated Installation section:
───────────────────────────────────────
## Installation

\`\`\`bash
pip install my-project
\`\`\`

For detailed setup and configuration, see [Setup Guide](docs/setup.md).
───────────────────────────────────────

Apply this simplification? (y/n):

Preserving Custom Content

If README has unique sections (FAQ, Roadmap, Changelog):

• Keep them at the end of README
• Maintain their order
• Don't flag as non-compliant
• Note in update summary

Related Commands

• /document-generator:validate-readme - Check README before/after update
• /document-generator:generate-readme - Create new README instead

Batch Update Mode

For non-interactive batch updates (--interactive=false):

• Apply all fixes automatically
• No user prompts
• Create detailed update log
• Save to ./reports/readme-update-log.md

Use with caution - Review changes carefully after batch update.