docs: refactor documentation and fix inconsistencies#3178
Merged
MarkusNeusinger merged 6 commits intomainfrom Jan 6, 2026
Merged
docs: refactor documentation and fix inconsistencies#3178MarkusNeusinger merged 6 commits intomainfrom
MarkusNeusinger merged 6 commits intomainfrom
Conversation
- Analyze current documentation structure and redundancy issues - Propose new organization by user persona (users/contributors/developers) - Streamline CLAUDE.md from 937 to <200 lines (rules only) - Separate concepts (WHY) from workflows (WHAT) from implementation (HOW) - Create clear navigation with docs/index.md as entry point - Include 4-phase migration plan with success metrics
Key changes: - CLAUDE.md stays comprehensive (600-700 lines, not <200) - Focus on better structure and removing internal redundancy - Clear separation: CLAUDE.md for AI, docs/ for humans - Keep all rules, workflows, and 'where things are' in CLAUDE.md - Remove duplicate explanations within CLAUDE.md - Eliminate duplication between CLAUDE.md and other docs
Key principle: Documentation describes what EXISTS, not what's planned Changes: - Add 'Document what exists' as primary philosophy - List unimplemented features to remove from docs - Identify files to delete (ab-testing, claude-skill concepts) - Move future plans to GitHub Issues/Milestones - Add verification questions (what's actually working?) To remove from docs: - Multi-LLM review (if not active) - User data upload / premium features - Rules versioning/A/B testing - Future optimization sections - API client SDKs that don't exist - Unverified social media/n8n workflows
Verified against actual codebase: EXISTS: - Single LLM review (Claude only via anthropics/claude-code-action) - Thumbnails (impl-generate.yml + core/images.py) - GCS staging/production workflow - Tagging in PostgreSQL JSONB - Basic API (specs, plots, libraries, health, download, stats) - OG image branding DOES NOT EXIST (remove from docs): - Multi-LLM review (Claude + Gemini + GPT) - /plots/generate endpoint - Premium tier - n8n workflows - Rules versioning / A/B testing - Python/JS client SDKs - Firestore Files to delete: - docs/concepts/ab-testing-rules.md - docs/concepts/claude-skill-plot-generation.md
- Rename documentation files for clarity - Update references in specification.yaml and other files - Improve descriptions in plot-types-catalog.md and README.md
- Add initial creation of metadata/{library}.yaml in impl-generate.yml
- Update metadata/{library}.yaml with quality score and review feedback in impl-review.yml
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors documentation structure and fixes inconsistencies between docs and actual workflow implementations. The changes include organizing documentation into concepts/, workflows/, and reference/ directories, translating German text to English, fixing incorrect references to workflow files and quality report storage locations, and updating GitHub repository links.
Key changes:
- Reorganized documentation into logical subdirectories (
concepts/,workflows/,reference/) - Fixed quality report references (changed from "GitHub Issues" to "metadata files")
- Corrected workflow file name references throughout documentation
- Translated remaining German text to English
- Updated GitHub repository references from placeholder to actual repo
Reviewed changes
Copilot reviewed 110 out of 114 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
prompts/templates/specification.yaml |
Updated tagging system reference path |
prompts/README.md |
Fixed workflow file names and library count |
plots/*/specification.yaml (78 files) |
Updated tagging system documentation path |
docs/workflows/overview.md |
New comprehensive workflow documentation |
docs/workflow.md |
Deleted old workflow documentation |
docs/specs-guide.md |
Deleted old specs guide |
docs/reference/tagging-system.md |
New location for tagging documentation |
docs/reference/seo.md |
New SEO configuration documentation |
docs/reference/repository.md |
Updated repository structure documentation |
docs/reference/plausible.md |
New analytics tracking documentation |
docs/reference/database.md |
Updated database documentation with corrected quality report references |
docs/reference/api.md |
New API reference documentation |
docs/plot-types-catalog.md |
Translated German descriptions to English |
docs/index.md |
New documentation index |
docs/development.md |
Refactored development guide |
docs/contributing.md |
New contributing guide |
docs/concepts/vision.md |
New product vision documentation |
docs/concepts/claude-skill-plot-generation.md |
Deleted obsolete documentation |
docs/concepts/ab-testing-rules.md |
Deleted obsolete documentation |
docs/architecture/api.md |
Deleted old API documentation |
README.md |
Updated documentation references and quality review description |
CLAUDE.md |
Updated quality report references and documentation paths |
.github/workflows/spec-create.yml |
Updated tagging system path reference |
.github/copilot-instructions.md |
Updated quality score description and anti-patterns |
.claude/commands/prime.md |
Updated documentation file references |
The changes are well-organized and appear to be comprehensive. All updates correctly reflect the move from scattered documentation to a structured hierarchy.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Key Changes
Documentation Fixes
your-repo→MarkusNeusinger/pyplots)>= 90, or >= 50 after 3 attempts)Instruction Files
gen-library-impl.yml→impl-generate.ymlgen-update-plot.yml→impl-repair.ymlbot-ai-review.yml→impl-review.ymlspec.md→specification.mdNew Files
Test plan
🤖 Generated with Claude Code