Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Dec 25, 2025

Documentation incorrectly stated task frontmatter is included in output, used inconsistent field naming (language vs languages), and had significant duplication across files.

Fixed Inaccuracies

  • Task frontmatter output: Corrected false claim that task frontmatter appears in assembled context. Only task content is included; frontmatter is used for filtering/metadata only.
  • Field naming: Standardized to languages (plural) throughout. The code uses languages: [] as an array field—docs now match.
  • Task name syntax: Removed incorrect slash prefix from examples (/fix-bugfix-bug).

Reduced Duplication

  • Installation instructions: Link to README instead of duplicating version-specific curl commands
  • Search paths: Reference docs/reference/search-paths.md instead of listing all 30+ locations
  • Getting started guide: Consolidated with clearer -p (parameters) vs -s (selectors) distinction

Added Missing Content

  • Troubleshooting section in README covering 5 common issues:
    • Task not found (filename matching, not task_name field)
    • No rules included (selector vs parameter flag confusion)
    • Parameters not substituted
    • Wrong rules included
    • Bootstrap scripts not executing

Example Correction

Before:

---
selectors:
  language: go
---
coding-context -s language=go fix-bug

After:

---
selectors:
  languages: go
---
coding-context -s languages=go fix-bug

Files modified: 8 docs (+94/-73 lines)

Original prompt

Review all documentation and find inaccuracies.
Then, look for duplication, and reduce it.
Then, look for omissions, and add them.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI changed the title [WIP] Review documentation for inaccuracies and omissions Fix documentation inaccuracies and reduce duplication Dec 25, 2025
Copilot AI requested a review from alexec December 25, 2025 23:49
@alexec alexec marked this pull request as ready for review December 26, 2025 01:51
Copilot AI review requested due to automatic review settings December 26, 2025 01:51
@alexec alexec enabled auto-merge (squash) December 26, 2025 01:51
@alexec alexec merged commit 680c5a4 into main Dec 26, 2025
5 checks passed
@alexec alexec deleted the copilot/review-documentation-accuracy branch December 26, 2025 01:52
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR corrects significant documentation inaccuracies and reduces duplication across documentation files. The primary fix addresses a false claim that task frontmatter appears in assembled context output - the code confirms that only task content is included. The PR also standardizes field naming from language (singular) to languages (plural) throughout documentation to match the typed field in the codebase, removes inconsistent slash prefix syntax from task examples, and consolidates duplicated content by linking to authoritative sources.

Key changes:

  • Corrected task frontmatter behavior documentation (frontmatter used for filtering/metadata only, not included in output)
  • Standardized to languages: (plural) field naming throughout all documentation
  • Removed incorrect slash prefix from task name syntax (fix-bug instead of /fix-bug)

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file
File Description
docs/tutorials/getting-started.md Simplified installation instructions to reference README, clarified parameter vs selector flags, removed slash prefix from task names
docs/reference/file-formats.md Corrected documentation stating task frontmatter is NOT included in output
docs/reference/cli.md Updated output format documentation to reflect task frontmatter exclusion and correct skills metadata positioning
docs/how-to/use-selectors.md Changed field name from language to languages, corrected frontmatter output expectations
docs/how-to/create-tasks.md Clarified that task frontmatter is used for filtering but NOT included in output
docs/how-to/create-rules.md Standardized field naming to languages: (plural)
SPECIFICATION.md Updated all selector examples to use languages: instead of language:
README.md Replaced duplicated search paths with link to reference docs, added comprehensive troubleshooting section

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants