# Tools Maintenance Guide - Annual Update Process

**Last Updated:** 2026-03-25

Comprehensive guide for maintaining and updating tools/calculators annually to ensure legal compliance and accuracy.

## Annual Update Process

### Timeline

**Q4 (October-December):** Research phase

- Monitor official sources for upcoming law changes
- Compile list of changes effective January 1
- Create update plan

**January:** Implementation phase

- Update high-priority tools (legal compliance)
- Update medium-priority tools (content accuracy)
- Update low-priority tools (year references)

**February:** Testing and validation phase

- Test all calculations
- Validate content accuracy
- Verify schema markup

**March:** Review and documentation phase

- Review user feedback
- Update documentation
- Document lessons learned

## Law Change Monitoring Checklist

### Sources to Monitor

**Quarterly Review:**

- [ ] **High-value tools (SEO):** Re-run `php v2/scripts/tools/run-tools-improvement-pipeline.php --tool={slug}` **Phase 1** (or `make tool-research TOOL={slug}`), diff `CONTENT_OUTLINE.md` / competitor JSON, then `python3 v2/scripts/tools/audit-tools-content-blocks.py {slug} --format-check`. Prioritize slugs in [TOOLS_PRIORITIZATION_2026.md](../../content/tools/TOOLS_PRIORITIZATION_2026.md) when rankings or CTR stall.
- [ ] Minijob-Zentrale: Minijob Grenze announcements
- [ ] Bundesagentur für Arbeit: ALG 1, Midijob updates
- [ ] Bundesministerium für Arbeit und Soziales: Social security rates, BBG values
- [ ] Bundesfinanzministerium: Tax constants, Grundfreibetrag
- [ ] TVöD/TV-L official sources: Tariff updates
- [ ] **Content Block SEO Audit** (before major content refresh): Run `python3 v2/scripts/tools/audit-tools-content-blocks.py [tool_slug] --keywords=...`; compare word count, internal links, keyword presence. See `.cursor/rules/tools-pages-content-blocks.mdc`
- [ ] **PayPal Gebührenrechner (Drittanbieter-Tarife):** PayPal DE [Händlergebühren](https://www.paypal.com/de/business/paypal-business-fees) und aktuelles PDF (`de-de-merchant-fees-*.pdf`) mit `v2/api/paypal_fees_config.json`, eingebettetem PHP-Fallback und sichtbarem Content (Tabellen, FAQs, Schema) abgleichen. Bei Mikro- oder Festgebühren-Änderungen Break-even-Werte neu berechnen und Alpine-Hinweise (z. B. EUR-Schwelle) anpassen.

**Annual Review (Q4):**

- [ ] Minimum wage announcements (Mindestlohn)
- [ ] Social security contribution ceilings (BBG)
- [ ] Tax law changes (Steuerreform)
- [ ] Labor law changes (Arbeitsrecht)

### Key Dates

- **October:** Official announcements typically published
- **November:** Final values confirmed
- **December:** Prepare update plan
- **January 1:** Changes take effect

## Update Workflow

### Phase 1: Research

1. **Identify Changes**

   - Review official sources
   - Compile list of affected tools
   - Document new values

2. **Verify Values**

   - Cross-reference multiple sources
   - Document source URLs
   - Note effective dates

3. **Create Update Plan**
   - Prioritize by compliance risk
   - Assign to team members
   - Set deadlines

### Phase 2: Code Updates

1. **Update Constants**

   - Update JavaScript constants files
   - Update inline constants in PHP
   - Update default values

2. **Update Calculations**

   - Verify formulas unchanged
   - Test with new values
   - Update validation rules if needed

3. **Update File References**
   - Update year in file names if applicable
   - Update version numbers
   - Update comments

### Phase 3: Content Updates

1. **Update Meta Tags**

   - Update titles (year references)
   - Update descriptions
   - Update keywords if needed

2. **Update Page Content**

   - Update H1 headings
   - Update descriptions
   - Update help text
   - Update educational content

3. **Update FAQs**
   - Review all FAQs for accuracy
   - Update year references
   - Update values mentioned
   - Add new FAQs if needed

### Phase 4: Testing

1. **Calculation Testing**

   - Test normal cases
   - Test edge cases
   - Verify against official sources
   - Document test results

2. **Content Testing**

   - Verify all year references updated
   - Verify legal information accurate
   - Verify FAQs accurate
   - Verify schema markup

3. **Browser Testing**
   - Test in Chrome
   - Test in Firefox
   - Test in Safari
   - Test on mobile devices

### Phase 5: Documentation

1. **Update Tool Documentation**

   - Update individual tool docs (`*-documentation.md` files)
   - Update "Last Updated" date to current date
   - Update constants section with new values
   - Update example calculations with new values
   - Update content sections (H1, descriptions, FAQs)
   - Update 2026 Update Requirements section (mark complete)
   - Document changes in change log section
   - Remove any "(pending verification)" notes

2. **Update Core Documentation**

   - Update `README.md` if structure changes
   - Update `TOOLS_MAINTENANCE_GUIDE.md` if process changes
   - Update `TOOL_DOCUMENTATION_TEMPLATE.md` if template changes
   - Update consolidated status files (`FINAL_STATUS_2026.md`, etc.)

3. **Update Cursor Rules**

   - Add new patterns if needed
   - Update examples with current values
   - Document best practices
   - Update documentation maintenance requirements

4. **Create Update Report**
   - Document all changes
   - Document verification sources
   - Document test results
   - Update consolidated status files

## Testing Procedures

### Calculation Testing

**For Each Tool:**

1. **Normal Cases**

   - Test with typical input values
   - Verify results match expected values
   - Compare with official calculators if available

2. **Edge Cases**

   - Test with zero values
   - Test with maximum values
   - Test with boundary values
   - Test with invalid inputs

3. **Verification**
   - Compare with official sources
   - Document calculation steps
   - Verify formulas unchanged

### Content Testing

**Checklist:**

- [ ] All "2025" references updated to "2026"
- [ ] Legal information accurate
- [ ] FAQs accurate and up-to-date
- [ ] Meta tags updated
- [ ] Schema markup valid
- [ ] Internal links working
- [ ] No broken references

### Browser Testing

**Checklist:**

- [ ] Chrome (desktop): All features working
- [ ] Firefox (desktop): All features working
- [ ] Safari (desktop): All features working
- [ ] Chrome (mobile): Responsive, touch-friendly
- [ ] Safari (mobile): Responsive, touch-friendly
- [ ] Export functionality: Excel, PDF, CSV working

## Documentation Standards

### Tool Documentation Requirements

Each tool must have:

- Overview (purpose, use cases, audience)
- Technical documentation (files, modes, constants)
- Calculation logic (formulas, examples)
- Content documentation (hero, FAQs, meta tags)
- Update requirements (what needs updating, when)

### Update Documentation Requirements

Each update must document:

- Values changed (old → new)
- Source of new values
- Files modified
- Test results
- Date of update

## Common Pitfalls to Avoid

### ❌ Don't:

- Update values without verifying from official sources
- Update content without updating calculations
- Skip testing after updates
- Forget to update documentation
- Update only some references (inconsistent)

### ✅ Do:

- Verify all values from official sources
- Update code and content together
- Test thoroughly after updates
- Document all changes
- Update all references consistently

## Emergency Update Process

If critical error found:

1. **Identify Issue**

   - Document the problem
   - Identify affected users
   - Assess severity

2. **Fix Immediately**

   - Update code/content
   - Test fix
   - Deploy fix

3. **Document**
   - Document the issue
   - Document the fix
   - Update testing procedures if needed

## Monitoring and Feedback

### User Feedback Channels

- Support emails
- User reports
- Analytics data
- Error logs

### Regular Reviews

- Monthly: Review user feedback
- Quarterly: Review official sources
- Annually: Comprehensive update process

## Tools and Resources

### Official Sources

- Minijob-Zentrale: https://www.minijob-zentrale.de/
- Bundesagentur für Arbeit: https://www.arbeitsagentur.de/
- Bundesministerium für Arbeit und Soziales: https://www.bmas.de/
- Bundesfinanzministerium: https://www.bundesfinanzministerium.de/

### Internal Resources

- Tool documentation: `docs/guides/tools-pages/`
- Cursor rules: `.cursor/rules/tools-pages-*.mdc`
- Update checklists: `docs/guides/tools-pages/IMMEDIATE_UPDATES_CHECKLIST_2026.md`

## Success Metrics

### Update Quality

- All values verified from official sources
- All calculations tested and accurate
- All content updated consistently
- All documentation updated

### User Impact

- No calculation errors reported
- No outdated information found
- Positive user feedback
- High tool usage

## Next Steps

1. **Q4 2026:** Begin monitoring for 2027 changes
2. **January 2027:** Execute annual update process
3. **Ongoing:** Monitor for mid-year changes
4. **Continuous:** Improve documentation and processes