docs: add ontology analysis references for skills #357
Conversation
📝 WalkthroughWalkthroughAdds bilingual Sowa-based ontology documentation and two reusable analysis frameworks, and links them as optional references across multiple skill SKILL.md files. All changes are documentation-only; no code, API, or executable logic modified. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@docs/knowledge/ontology-agents.md`:
- Line 3: Replace the bare URL "https://www.jfsowa.com/ontology/agents.htm" with
a Markdown link so the file no longer contains a naked URL; update the text to
use the standard Markdown link format
[source](https://www.jfsowa.com/ontology/agents.htm) (or a more descriptive
label like [J. F. Sowa — Ontology of
Agents](https://www.jfsowa.com/ontology/agents.htm)) to satisfy MD034 and avoid
lint warnings.
In `@skills/brainstorming/references/agents-analysis-framework.md`:
- Line 3: Replace the bare URL "https://www.jfsowa.com/ontology/agents.htm" with
a Markdown link to avoid MD034 lint failures; update the "Source:
https://www.jfsowa.com/ontology/agents.htm" line to use explicit link text
(e.g., "Source: [Agents Ontology — J. F.
Sowa](https://www.jfsowa.com/ontology/agents.htm)") so the file
"agents-analysis-framework.md" contains a proper Markdown link instead of a raw
URL.
In `@skills/brainstorming/references/toplevel-analysis-framework.md`:
- Line 3: Replace the bare URL after the "Source:" prefix with a Markdown link
(e.g., [Toplevel Ontology](https://www.jfsowa.com/ontology/toplevel.htm));
locate the "Source:" line in toplevel-analysis-framework.md and change it so the
URL is wrapped in square brackets with an explanatory link text followed by the
URL in parentheses to avoid MD034 lint errors.
In `@skills/executing-plans/references/agents-analysis-framework.md`:
- Line 3: Replace the bare URL "https://www.jfsowa.com/ontology/agents.htm" with
a Markdown link (e.g., [J.F. Sowa —
Agents](https://www.jfsowa.com/ontology/agents.htm)) to avoid MD034 lint errors;
update the reference in the document so the URL is enclosed in [text](url)
format and ensure surrounding punctuation/spacing remains correct.
In `@skills/requesting-code-review/references/agents-analysis-framework.md`:
- Line 3: Replace the bare URL "https://www.jfsowa.com/ontology/agents.htm" with
a Markdown link to satisfy MD034; edit the line in the document so the URL is
formatted as a link with descriptive link text (e.g., "Agents ontology by John
Sowa") using the [text](https://www.jfsowa.com/ontology/agents.htm) style.
In `@skills/requesting-code-review/references/toplevel-analysis-framework.md`:
- Line 3: Replace the bare URL in the line "Source:
https://www.jfsowa.com/ontology/toplevel.htm" with a proper Markdown link (e.g.,
Source: [J. F. Sowa — Top-level
Ontology](https://www.jfsowa.com/ontology/toplevel.htm)) so the URL is not bare
and the file satisfies MD034; update the exact text that contains that URL.
🧹 Nitpick comments (7)
skills/writing-plans/references/agents-analysis-framework.md (1)
3-3: Format the source URL as a proper markdown link.The bare URL should be formatted as a markdown link for better readability and consistency with markdown best practices.
🔗 Proposed fix
-Source: https://www.jfsowa.com/ontology/agents.htm +Source: [Sowa's Ontology: Agents](https://www.jfsowa.com/ontology/agents.htm)skills/writing-plans/references/toplevel-analysis-framework.md (1)
3-3: Format the source URL as a proper markdown link.The bare URL should be formatted as a markdown link for better readability and consistency with markdown best practices.
🔗 Proposed fix
-Source: https://www.jfsowa.com/ontology/toplevel.htm +Source: [Sowa's Ontology: Top-Level Categories](https://www.jfsowa.com/ontology/toplevel.htm)skills/brainstorming/references/agents-analysis-framework.md (1)
28-28: Hyphenate “one-sentence” for style consistency.Optional: improves readability in lists.
✍️ Proposed tweak
-- Intent summary: one sentence purpose. +- Intent summary: one-sentence purpose.skills/requesting-code-review/references/agents-analysis-framework.md (1)
28-28: Hyphenate “one-sentence” for style consistency.Optional style polish.
✍️ Proposed tweak
-- Intent summary: one sentence purpose. +- Intent summary: one-sentence purpose.skills/executing-plans/references/agents-analysis-framework.md (1)
28-28: Hyphenate “one-sentence” for style consistency.Optional style cleanup.
✍️ Proposed tweak
-- Intent summary: one sentence purpose. +- Intent summary: one-sentence purpose.docs/knowledge/ontology-toplevel.md (1)
3-3: Format the bare URL as a markdown link.The source URL should be formatted as a markdown link for better readability and to comply with markdown best practices.
📝 Proposed fix
-Source: https://www.jfsowa.com/ontology/toplevel.htm +Source: [https://www.jfsowa.com/ontology/toplevel.htm](https://www.jfsowa.com/ontology/toplevel.htm)skills/executing-plans/references/toplevel-analysis-framework.md (1)
3-3: Format the bare URL as a markdown link.The source URL should be formatted as a markdown link for consistency with markdown best practices.
📝 Proposed fix
-Source: https://www.jfsowa.com/ontology/toplevel.htm +Source: [https://www.jfsowa.com/ontology/toplevel.htm](https://www.jfsowa.com/ontology/toplevel.htm)
skills/requesting-code-review/references/agents-analysis-framework.md
Outdated
Show resolved
Hide resolved
skills/requesting-code-review/references/toplevel-analysis-framework.md
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@skills/executing-plans/references/agents-analysis-framework.md`:
- Around line 27-29: Update the "Intent summary" bullet under the "Output
Mapping (for planning/review)" section to use a hyphenated form: change "one
sentence purpose." to "one-sentence purpose." so the line reads "Intent summary:
one-sentence purpose." (refer to the "Output Mapping (for planning/review)"
header and the "Intent summary" bullet).
In `@skills/requesting-code-review/references/agents-analysis-framework.md`:
- Around line 27-29: Update the bullet under "Output Mapping (for
planning/review)" that reads "- Intent summary: one sentence purpose." to use a
hyphenated adjective by changing it to "- Intent summary: one-sentence purpose."
— locate the "Intent summary" bullet in the Output Mapping section and apply the
hyphen to "one-sentence."
| ## Output Mapping (for planning/review) | ||
| - Intent summary: one sentence purpose. | ||
| - Capability boundaries: explicit in-scope/out-of-scope list. |
There was a problem hiding this comment.
Use a hyphen in “one-sentence.”
Minor grammar/style: “one-sentence purpose” reads cleaner and avoids lint warnings.
✏️ Proposed edit
- - Intent summary: one sentence purpose.
+ - Intent summary: one-sentence purpose.🧰 Tools
🪛 LanguageTool
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...r planning/review) - Intent summary: one sentence purpose. - Capability boundarie...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In `@skills/executing-plans/references/agents-analysis-framework.md` around lines
27 - 29, Update the "Intent summary" bullet under the "Output Mapping (for
planning/review)" section to use a hyphenated form: change "one sentence
purpose." to "one-sentence purpose." so the line reads "Intent summary:
one-sentence purpose." (refer to the "Output Mapping (for planning/review)"
header and the "Intent summary" bullet).
| ## Output Mapping (for planning/review) | ||
| - Intent summary: one sentence purpose. | ||
| - Capability boundaries: explicit in-scope/out-of-scope list. |
There was a problem hiding this comment.
Use a hyphen in “one-sentence.”
Minor grammar/style: “one-sentence purpose” reads cleaner and avoids lint warnings.
✏️ Proposed edit
- - Intent summary: one sentence purpose.
+ - Intent summary: one-sentence purpose.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Output Mapping (for planning/review) | |
| - Intent summary: one sentence purpose. | |
| - Capability boundaries: explicit in-scope/out-of-scope list. | |
| ## Output Mapping (for planning/review) | |
| - Intent summary: one-sentence purpose. | |
| - Capability boundaries: explicit in-scope/out-of-scope list. |
🧰 Tools
🪛 LanguageTool
[grammar] ~28-~28: Use a hyphen to join words.
Context: ...r planning/review) - Intent summary: one sentence purpose. - Capability boundarie...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In `@skills/requesting-code-review/references/agents-analysis-framework.md` around
lines 27 - 29, Update the bullet under "Output Mapping (for planning/review)"
that reads "- Intent summary: one sentence purpose." to use a hyphenated
adjective by changing it to "- Intent summary: one-sentence purpose." — locate
the "Intent summary" bullet in the Output Mapping section and apply the hyphen
to "one-sentence."
1 participant
Added bilingual knowledge docs and per-skill analysis frameworks based on Sowa’s ontology, wired into brainstorming/write-plan/execute-plan/review as optional references with clear usage/adaptation guidance.
Motivation and Context
Provides a structured analysis framework to strengthen requirement clarification and content design without changing Superpowers workflows. It localizes the ontology concepts to Superpowers stages and makes them reusable.
How Has This Been Tested?
Not applicable (documentation-only change).
Breaking Changes
No.
Types of changes
Checklist
Additional context
References are optional and explicitly do not alter the existing workflow; they only enhance analysis and coverage during clarification/planning/review.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.