fix: documentation category cleanup#67
Conversation
Greptile SummaryThis PR performs a documentation category cleanup across 77 Key changes:
Observations:
Confidence Score: 5/5Safe to merge — all remaining findings are P2 style suggestions that don't block correctness or functionality. All 35 deletions are appropriate stub removals. The 42 updates significantly improve the category. The only issues found are P2 quality suggestions about template reuse and one template mismatch — neither prevents the skills from functioning or causes data/logic errors. skills/documentation/scientific-slides/SKILL.md and the 13 other files sharing its identical body template; also skills/documentation/jupyter-notebook/SKILL.md for template fit. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[77 SKILL.md files in PR] --> B{Content type?}
B -->|Generic stub boilerplate| C[35 files DELETED]
B -->|Substantive new content| D[42 files UPDATED]
D --> E{Content source?}
E -->|Tailored per-skill content| F[~28 files\ne.g. agent-memory, write-release-notes,\ncreate-skill-file, packages]
E -->|Generic docs-writing template| G[~14 files\ne.g. seo-audit, scientific-slides,\nwiki-onboarding, tutorial-engineer]
E -->|Platform docs template| H[3 files\nmintlify, openai-docs, jupyter-notebook]
F --> I[✅ Unique workflow + pitfalls + boundaries]
G --> J[⚠️ Identical body across 14 skills]
H --> K[⚠️ jupyter-notebook: weak template fit]
C --> L[All deleted files confirmed\nas placeholder stubs]
Reviews (1): Last reviewed commit: "fix: documentation category cleanup" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - "Draft scientific slide docs for this project so readers can act without guessing." | ||
| - "Review scientific slide docs for missing prerequisites, stale assumptions, and unclear steps." | ||
| --- | ||
|
|
||
| # Scientific Slides | ||
|
|
||
| Support scientific slides workflows with clear steps and best practices. | ||
| Use this skill when the user is writing, reviewing, or restructuring scientific slide docs and needs the result to be readable, trustworthy, and genuinely useful after publication. | ||
|
|
||
| ## When to Use | ||
| ## Start By Clarifying | ||
| - Who the readers are and what they are trying to accomplish. | ||
| - What source material or product truth the document should rely on. | ||
| - Which prerequisites, assumptions, or environment details must be explicit. | ||
| - What is likely to change over time and how freshness will be maintained. | ||
| - Whether the document should teach, orient, review, or support troubleshooting. | ||
|
|
||
| - You need help with scientific slides. | ||
| - You want a clear, actionable next step. | ||
| ## Workflow | ||
| 1. Define the audience, the primary reader questions, and the desired outcome. | ||
| 2. Gather accurate source material from code, product behavior, or subject-matter owners. | ||
| 3. Organize the document around reader tasks, decisions, or mental models rather than internal org charts. | ||
| 4. Add concrete examples, checklists, or comparisons where they reduce ambiguity. | ||
| 5. Review for gaps, stale assumptions, and missing ownership before calling it complete. | ||
|
|
||
| ## Output | ||
| ## Good Output | ||
| - Recommended document structure and section order. | ||
| - Gaps in reader context, prerequisites, or examples. | ||
| - Suggested revisions for clarity, accuracy, and maintainability. | ||
| - Update triggers or ownership notes for future freshness. | ||
|
|
||
| - Summary of goals and plan | ||
| - Key tips and precautions | ||
| ## Common Pitfalls | ||
| - Writing for insiders and assuming too much prior knowledge. | ||
| - Burying prerequisites or caveats after the main steps. | ||
| - Leaving examples too abstract to help real readers. | ||
| - Publishing docs with no clear owner or update trigger. | ||
|
|
||
| ## Boundaries | ||
| - Do not present guesses as verified facts. | ||
| - Prefer reader tasks and decision support over internal jargon or filler. |
There was a problem hiding this comment.
The body content of this skill (all of ## Start By Clarifying, ## Workflow, ## Good Output, ## Common Pitfalls, and ## Boundaries) is word-for-word identical to at least 13 other updated skills in this PR: seo-audit, wiki-onboarding, docs-style, tutorial-engineer, web-design-guidelines, web-design-reviewer, environment-setup-guide, docs-architect, docs-sync, doc-coauthoring, review-docs, project-overview, and crafting-effective-readmes.
For a skill focused on scientific slides, this generic template includes guidance like "Organize the document around reader tasks, decisions, or mental models rather than internal org charts" and "Gather accurate source material from code, product behavior" — neither of which is relevant. Slide-specific guidance (visual hierarchy, slide-per-concept structure, speaker notes, figure/table captions, reproducibility of results) is entirely absent.
The descriptions and frontmatter examples are unique per file (good), but the body content provides no differentiated guidance. Consider either:
- Adding a
## Scientific Slides–Specific Guidancesection with domain-appropriate advice - Or consolidating these skills under a single generic
documentationparent skill and keeping only the truly distinct ones as standalone files
This same concern applies to all 13 other files sharing the identical template body listed above.
| - "Set up Jupyter notebook docs with structure, publishing rules, and maintenance ownership." | ||
| - "Review Jupyter notebook docs for navigation problems, stale content risk, and weak source-of-truth boundaries." | ||
| --- | ||
|
|
||
| # Jupyter Notebook | ||
|
|
||
| Support jupyter notebook workflows with clear steps and best practices. | ||
| Use this skill when the user is structuring or reviewing Jupyter notebook docs and needs documentation that fits the platform without pretending to have hidden publishing or backend powers. | ||
|
|
||
| ## When to Use | ||
| ## Start By Clarifying | ||
| - What content belongs on the platform and what should remain elsewhere. | ||
| - Who owns publishing, review, and long-term maintenance. | ||
| - How readers discover content through navigation, search, or links. | ||
| - What source-of-truth rules prevent drift between platform pages and other docs. | ||
| - Which examples, screenshots, or platform-specific conventions need active upkeep. | ||
|
|
||
| - You need help with jupyter notebook. | ||
| - You want a clear, actionable next step. | ||
| ## Workflow | ||
| 1. Define the information architecture and where each document type belongs. | ||
| 2. Set authorship, review, and publishing expectations before adding content at scale. | ||
| 3. Write or reorganize pages around reader tasks and stable navigation paths. | ||
| 4. Add freshness cues, ownership notes, and update triggers for high-change content. | ||
| 5. Review the platform for searchability, duplication, and stale or conflicting pages. | ||
|
|
||
| ## Output | ||
| ## Good Output | ||
| - Recommended page structure and navigation model. | ||
| - Source-of-truth boundaries and ownership expectations. | ||
| - Publishing or review workflow guidance. | ||
| - Risks around stale content, duplicated pages, or misleading examples. | ||
|
|
||
| - Summary of goals and plan | ||
| - Key tips and precautions | ||
| ## Common Pitfalls | ||
| - Treating the platform as the information architecture instead of designing one. | ||
| - Duplicating content in multiple places with no freshness rule. | ||
| - Publishing screenshots or examples that age quickly without maintenance ownership. | ||
| - Implying platform capabilities or automation that the user has not confirmed. | ||
|
|
||
| ## Boundaries | ||
| - Do not imply direct access to publishing systems unless the user provides it. | ||
| - Prefer platform-aware structure and governance over tool-magic claims. |
There was a problem hiding this comment.
This file uses the same "platform docs" template as mintlify and openai-docs — tools that are first-class documentation publishing platforms. The body references "screenshots, platform-specific conventions" and warns "Do not imply direct access to publishing systems unless the user provides it," which doesn't map well to Jupyter notebooks (a local/cloud notebook execution environment, not a publishing system).
Jupyter-notebook-specific guidance would more naturally cover: cell and output documentation, kernel/environment setup, reproducibility conventions (clearing outputs before commit, pinning dependencies), narrative prose structure vs. executable cells, and exporting/sharing considerations.
The same template is also used at skills/documentation/mintlify/SKILL.md and skills/documentation/openai-docs/SKILL.md — those two are a reasonable fit, but jupyter-notebook stands out as a mismatch.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
No description provided.