Enhance abstract skill for DITA short descriptions by Lennonka · Pull Request #4814 · theforeman/foreman-documentation

Lennonka · 2026-05-05T20:14:10Z

What changes are you introducing?

Enhancing the abstract AI skill with instructions for DITA short descriptions

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

To achieve higher quality of AI work

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

These instructions come from DITA reference.

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

github-actions · 2026-05-05T20:18:28Z

The PR preview for e688592 is available at theforeman-foreman-documentation-preview-pr-4814.surge.sh

No diff compared to the current base

show diff

Lennonka · 2026-05-05T20:19:14Z

Going to test it.

Lennonka · 2026-05-05T22:28:14Z

TBH, I have no idea if the results are better or worse now... see #4815 (raw AI output, single latest attempt, no manual editing)

@aneta-petrova @jafiala Care to try it out too?

Lennonka · 2026-05-06T20:13:43Z

This took two attempts and minor manual editing, but I think the result is pretty good: #4822

aneta-petrova · 2026-05-07T16:13:06Z

+- For module-type-specific abstract rules, look up the reference file that matches the `:_mod-docs-content-type:` AsciiDoc attribute in the module (open and apply that file in full):
+  - `CONCEPT` → [references/concept.md](references/concept.md)
+  - `PROCEDURE` → [references/procedure.md](references/procedure.md)
+  - `REFERENCE` → [references/reference.md](references/reference.md)


Would it be possible to include the specific guidelines here instead of in separate files? Or does the approach with separate files have any benefits?

Or actually, how about we pull in modular templates as a separate skill/skill reference, and include these specifics in those templates? Pulling the templates into this repo was proposed before in #4722, and I was against it, but I'm not sure how much longer the modular guides and templates will keep being supported and updates. Perhaps it's time we took ownership of them here as a project resource? Then these abstract instructions could be integrated with the abstract part of each template.

What do modular templates have to do with the content of short descriptions?

Separating the specific instructions for each type - I did that based on best practices for agent skills.

Fair enough, I can look into it myself later.

aneta-petrova · 2026-05-20T08:15:12Z

+
+- Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "Why do I care about this?"
+- If the concept is unfamiliar, start with a brief definition.
+- Avoid using the short description to lead in or build up to a topic.


What does this mean? A short description does introduce a topic.

It's supposed to summarize the topic, not introduce it.

aneta-petrova · 2026-05-20T08:24:08Z

+
+When the module has `:_mod-docs-content-type: REFERENCE`, follow these rules for the abstract (short description):
+
+- Briefly describe what the reference item does, what it is, or what it is used for.


"reference item" seems unclear

It's the "thing being referenced in the module". I don't know how else to call it. It seems clear enough to me. I'm open to suggestions.

jafiala · 2026-05-21T14:41:45Z

Seems to work well enough for me.
#4871
Only thing, it used "using" instead of "by using" a couple times.

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Co-authored-by: Aneta Petrová <apetrova@redhat.com> Co-authored-by: Lena Ansorge <zuansorg@redhat.com>

Lennonka · 2026-05-21T16:00:19Z

Rebased.

Lennonka · 2026-05-21T16:01:32Z

Seems to work well enough for me. #4871 Only thing, it used "using" instead of "by using" a couple times.

Thank you, @jafiala! This is one of those details we will have to clean up when we start adding Rules because it isn't specific to any skill.

Lennonka · 2026-05-21T16:03:23Z

I've tested it on #4870 and got quite good results too. Marking it as "testing done".

Lennonka · 2026-05-27T13:51:29Z

Since there haven't been any further comments, I'm considering this acked.

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Lennonka · 2026-05-27T13:54:38Z

Cherry picked:

c81d082..29464c9 3.19 -> 3.19
2a9da7e..766e13b 3.18 -> 3.18

Lennonka added this to the Prepare for DITA migration (RH) milestone May 5, 2026

pr-processor Bot added the Not yet reviewed label May 5, 2026

github-actions Bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective labels May 5, 2026

Lennonka commented May 5, 2026

View reviewed changes

Comment thread .cursor/skills/abstract/SKILL.md Outdated

pr-processor Bot removed the Not yet reviewed label May 5, 2026

Lennonka added Needs testing Requires functional testing and removed Needs tech review Requires a review from the technical perspective labels May 5, 2026

Lennonka requested a review from aneta-petrova May 5, 2026 20:19

Lennonka marked this pull request as draft May 5, 2026 20:53

Lennonka mentioned this pull request May 5, 2026

Review abstracts in Adding content #4815

Closed

9 tasks

Lennonka marked this pull request as ready for review May 5, 2026 22:30

Lennonka commented May 5, 2026

View reviewed changes

Comment thread .cursor/skills/abstract/SKILL.md Outdated

Lennonka requested a review from jafiala May 6, 2026 06:45

Lennonka commented May 6, 2026

View reviewed changes

Comment thread .claude/skills/abstract/SKILL.md

aneta-petrova reviewed May 7, 2026

View reviewed changes

Comment thread .cursor/skills/abstract/SKILL.md Outdated

aneta-petrova reviewed May 7, 2026

View reviewed changes

Comment thread .cursor/skills/abstract/SKILL.md

aneta-petrova reviewed May 7, 2026

View reviewed changes

aneta-petrova requested changes May 20, 2026

View reviewed changes

pr-processor Bot added Waiting on contributor Requires an action from the author Needs re-review and removed Waiting on contributor Requires an action from the author Needs re-review labels May 20, 2026

Lennonka requested a review from aneta-petrova May 20, 2026 13:49

Enhance abstract skill for DITA short descriptions

779de82

Lennonka and others added 13 commits May 21, 2026 17:59

Apply suggestion from @Lennonka

5d24fe6

Enforce instructions for module types

9941009

Clean up generic instructions

98a5f4d

Reorder stuff

556cd90

Drop example keyword to enforce usage

f962926

Improve content type following

3d32b37

Extract content-type specific instructions to references

7f8e893

Move examples to references

85081dc

Fine tune wording

3b77ef0

Incorporate feedback

33fc77f

Apply suggestions from review

b9055e6

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Apply suggestion from @aneta-petrova

57f41ce

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Apply suggestions from review

e688592

Co-authored-by: Aneta Petrová <apetrova@redhat.com> Co-authored-by: Lena Ansorge <zuansorg@redhat.com>

Lennonka force-pushed the enhance-abstract-skill-for-DITA-shortdesc branch from 4550ebe to e688592 Compare May 21, 2026 15:59

Lennonka added testing done No issues from the functional perspective and removed Needs testing Requires functional testing labels May 21, 2026

Lennonka merged commit 46c4b23 into theforeman:master May 27, 2026
8 checks passed

Lennonka added a commit that referenced this pull request May 27, 2026

Enhance abstract skill for short descriptions (#4814)

29464c9

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Lennonka added a commit that referenced this pull request May 27, 2026

Enhance abstract skill for short descriptions (#4814)

766e13b

Co-authored-by: Aneta Petrová <apetrova@redhat.com>

Lennonka deleted the enhance-abstract-skill-for-DITA-shortdesc branch May 27, 2026 13:54


		When the module has `:_mod-docs-content-type: REFERENCE`, follow these rules for the abstract (short description):

		- Briefly describe what the reference item does, what it is, or what it is used for.

Conversation

Lennonka commented May 5, 2026

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lennonka commented May 5, 2026

Uh oh!

Lennonka commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Lennonka commented May 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova May 7, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova May 8, 2026

Choose a reason for hiding this comment

Uh oh!

Lennonka May 19, 2026

Choose a reason for hiding this comment

Uh oh!

aneta-petrova May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aneta-petrova May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Lennonka May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Lennonka May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jafiala commented May 21, 2026

Uh oh!

Lennonka commented May 21, 2026

Uh oh!

Lennonka commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Lennonka commented May 21, 2026

Uh oh!

Lennonka commented May 27, 2026

Uh oh!

Uh oh!

Lennonka commented May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented May 5, 2026 •

edited

Loading

Lennonka commented May 5, 2026 •

edited

Loading

Lennonka May 20, 2026 •

edited

Loading

Lennonka commented May 21, 2026 •

edited

Loading