Claude commands to file Jiras#152
Merged
tisnik merged 3 commits intoJun 17, 2026
Merged
Conversation
WalkthroughAdds ChangesJIRA Filing Command Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/commands/file-jiras.md:
- Around line 42-44: The documentation for the parent_epic_file metadata comment
does not explicitly explain what <stub> represents. Add a one-sentence
clarification after line 42 in the file-jiras.md document explaining that <stub>
is the filename stem of the Epic file (for example, epic-name for a file named
epic-name.md), so users understand the expected format for the metadata comment
pattern.
- Line 1: The first line of the file must be formatted as a top-level markdown
heading to comply with markdown best practices and the markdownlint MD041 rule.
Convert the first line "Parse proposed JIRAs from a spike doc and file them via
the Jira API" into a proper markdown heading by prefixing it with a single hash
symbol and space at the beginning.
- Around line 1-95: The command definition file references two scripts
(dev-tools/file-jiras.sh and dev-tools/jira-common.sh) that do not exist in the
repository, making this documentation invalid and unverifiable. Either implement
these two scripts according to the specifications described in the
documentation, or if these tools are not part of this project, remove the
.claude/commands/file-jiras.md file entirely or update it to reference only
scripts and tools that actually exist in the codebase.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: da0943e8-945e-40e6-a33f-c22fe60a35a4
📒 Files selected for processing (1)
.claude/commands/file-jiras.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: e2e_tests
🧰 Additional context used
🪛 markdownlint-cli2 (0.22.1)
.claude/commands/file-jiras.md
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
| @@ -0,0 +1,95 @@ | |||
| Parse proposed JIRAs from a spike doc and file them via the Jira API | |||
There was a problem hiding this comment.
Add a top-level markdown heading to the first line.
Markdown best practices (and the markdownlint MD041 rule) require the first line to be a top-level heading (#). Currently, the file begins with plain text.
📝 Proposed fix
-Parse proposed JIRAs from a spike doc and file them via the Jira API
+# Parse proposed JIRAs from a spike doc and file them via the Jira API📝 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.
Suggested change
| Parse proposed JIRAs from a spike doc and file them via the Jira API | |
| # Parse proposed JIRAs from a spike doc and file them via the Jira API |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/file-jiras.md at line 1, The first line of the file must be
formatted as a top-level markdown heading to comply with markdown best practices
and the markdownlint MD041 rule. Convert the first line "Parse proposed JIRAs
from a spike doc and file them via the Jira API" into a proper markdown heading
by prefixing it with a single hash symbol and space at the beginning.
Source: Linters/SAST tools
Comment on lines
+1
to
+95
| Parse proposed JIRAs from a spike doc and file them via the Jira API | ||
|
|
||
| You are filing JIRA sub-tickets for a Lightspeed Core feature. | ||
|
|
||
| The user will provide either a spike doc path or tell you which feature's | ||
| JIRAs to file. They will also provide the feature ticket number. | ||
|
|
||
| Run `sh dev-tools/file-jiras.sh --help` to see the full usage. | ||
|
|
||
| ## Credentials | ||
|
|
||
| Jira credentials are managed by `dev-tools/jira-common.sh`. If | ||
| `~/.config/jira/credentials.json` doesn't exist, the script creates it | ||
| with FIXMEs and exits — the user must fill in their credentials before | ||
| re-running. API tokens can be created at | ||
| https://id.atlassian.com/manage-profile/security/api-tokens | ||
|
|
||
| ## Spike doc shape the parser expects | ||
|
|
||
| `file-jiras.sh` parses the spike doc's `## Proposed JIRAs` section into | ||
| Epic-grouped tickets: | ||
|
|
||
| ```markdown | ||
| ## Proposed JIRAs | ||
|
|
||
| ### Epic: <epic-name> | ||
|
|
||
| <epic prose: Goals, optional Scope, Success criteria> | ||
|
|
||
| #### LCORE-???? <child title> ← H4, child of the Epic above | ||
| <child body> | ||
|
|
||
| #### LCORE-???? <another child> | ||
| <child body> | ||
|
|
||
| ### Epic: <another epic-name> ← optional second Epic | ||
| ... | ||
| ``` | ||
|
|
||
| Each `### Epic: <name>` becomes a filed Epic; each `#### LCORE-????` | ||
| under it becomes a child of that Epic. Children carry a | ||
| `<!-- parent_epic_file: <stub> -->` metadata comment in their parsed | ||
| files; the script uses this to route each child to its parent Epic's | ||
| filed key at filing time. | ||
|
|
||
| **Backward-compat**: spike docs without `### Epic:` boundaries (flat | ||
| `### LCORE-...` H3 stubs directly under `## Proposed JIRAs`) still | ||
| parse — they get a single auto-generated Epic derived from the spike | ||
| doc's parent directory name. | ||
|
|
||
| **Already-filed keys**: if a heading reads `### LCORE-1569: <title>` | ||
| (or `#### LCORE-1569: ...`), the parser preserves the real key in the | ||
| output file. At filing time, the script sends a PUT (update) instead | ||
| of a POST (create), useful for re-syncing previously-filed tickets | ||
| with updated descriptions. | ||
|
|
||
| **Incidental tickets** (under `## Proposed incidental JIRAs`) file | ||
| under the feature ticket directly, not under any Epic. | ||
|
|
||
| ## Process | ||
|
|
||
| 1. Run `dev-tools/file-jiras.sh --spike-doc <path> --feature-ticket <key> --parse-only` | ||
| to parse the spike doc into ticket files and exit. `--parse-only` skips | ||
| the interactive filing loop and the credentials check, so it works | ||
| even on machines without Jira credentials configured (CI, agent | ||
| inspection, pre-commit hooks). | ||
|
|
||
| 2. Read every file in the output directory (default: `docs/design/<feature>/jiras/`). | ||
| For each, verify: | ||
| - Content matches the corresponding section in the spike doc (no truncation, | ||
| no extra content swallowed from subsequent sections). | ||
| - File size is reasonable (a single JIRA should be under ~3KB; if any file | ||
| is much larger, the parser likely grabbed too much). | ||
| - The `<!-- type: ... -->` metadata is correct (Epic/Story/Task). | ||
| - For children: `<!-- parent_epic_file: <stub> -->` points at an | ||
| existing Epic file in the same directory. | ||
|
|
||
| 3. Watch the parser's stderr for `[LINT-WARNING]` lines (mixed shape, | ||
| empty Epics, duplicate titles). `[LINT-ERROR]` causes the parser | ||
| to exit non-zero — fix the spike doc and re-run. | ||
|
|
||
| 4. Report any issues to the user. If all files look correct, tell the user | ||
| to run the script interactively — provide the full command including `cd` | ||
| to the repository root: | ||
| `cd <repo-path> && sh dev-tools/file-jiras.sh --spike-doc <path> --feature-ticket <key>` | ||
|
|
||
| ## Filing order | ||
|
|
||
| The script files Epics first, then their children. With multi-Epic | ||
| spike docs, this means Epic A is filed → its children land under Epic | ||
| A → Epic B is filed → its children land under Epic B. Children whose | ||
| parent Epic hasn't been filed yet error out clearly; file the Epic | ||
| first and retry. | ||
|
|
||
| Incidental tickets file last (under FEATURE_TICKET, no Epic parent). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify that the referenced scripts exist and contain expected behavior patterns.
# Check for script existence
test -f dev-tools/file-jiras.sh && echo "✓ dev-tools/file-jiras.sh exists" || echo "✗ dev-tools/file-jiras.sh missing"
test -f dev-tools/jira-common.sh && echo "✓ dev-tools/jira-common.sh exists" || echo "✗ dev-tools/jira-common.sh missing"
# Check for key patterns in file-jiras.sh
echo ""
echo "=== Checking for documented behavior patterns in file-jiras.sh ==="
if [ -f dev-tools/file-jiras.sh ]; then
echo "Checking for '--parse-only' flag:"
grep -n "\-\-parse-only" dev-tools/file-jiras.sh || echo " (not found)"
echo "Checking for metadata patterns (parent_epic_file, type:):"
grep -n "parent_epic_file\|<!-- type:" dev-tools/file-jiras.sh || echo " (not found)"
echo "Checking for lint warning patterns:"
grep -n "LINT-WARNING\|LINT-ERROR" dev-tools/file-jiras.sh || echo " (not found)"
echo "Checking for output directory default (docs/design):"
grep -n "docs/design" dev-tools/file-jiras.sh || echo " (not found)"
fi
echo ""
echo "=== Checking credentials file path in jira-common.sh ==="
if [ -f dev-tools/jira-common.sh ]; then
grep -n "\.config/jira/credentials" dev-tools/jira-common.sh || echo " (not found)"
fiRepository: lightspeed-core/lightspeed-providers
Length of output: 275
🏁 Script executed:
# Check if dev-tools directory exists
ls -la dev-tools/ 2>/dev/null || echo "dev-tools directory not found"
# Search for any jira-related files in the entire repository
echo ""
echo "=== Searching for jira-related files ==="
fd -i "jira" --type f
# Check if there are any shell scripts in dev-tools (if it exists)
echo ""
echo "=== Shell scripts in dev-tools ==="
find dev-tools -name "*.sh" -type f 2>/dev/null || echo "(no dev-tools directory or no .sh files)"Repository: lightspeed-core/lightspeed-providers
Length of output: 229
🏁 Script executed:
# Check if the reviewed file exists
ls -la .claude/commands/file-jiras.md
# List what's in the .claude/commands directory
echo ""
echo "=== Contents of .claude/commands/ ==="
ls -la .claude/commands/ 2>/dev/null || echo "Directory not found"
# Check if there's a .claude directory at all
echo ""
echo "=== Check for .claude directory ==="
find . -type d -name ".claude" 2>/dev/null | head -20Repository: lightspeed-core/lightspeed-providers
Length of output: 494
Scripts referenced in this command definition do not exist in the repository.
The documentation describes behavior for dev-tools/file-jiras.sh and dev-tools/jira-common.sh, but neither script nor the dev-tools/ directory exists in the codebase. Since this is a .claude/commands/ definition file intended to guide tool usage, either: (1) these scripts need to be implemented before this command documentation is valid, (2) this documentation is orphaned from a previous project, or (3) it describes an external process not yet integrated here. The command cannot be verified or executed as currently documented.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/file-jiras.md around lines 1 - 95, The command definition
file references two scripts (dev-tools/file-jiras.sh and
dev-tools/jira-common.sh) that do not exist in the repository, making this
documentation invalid and unverifiable. Either implement these two scripts
according to the specifications described in the documentation, or if these
tools are not part of this project, remove the .claude/commands/file-jiras.md
file entirely or update it to reference only scripts and tools that actually
exist in the codebase.
Comment on lines
+42
to
+44
| `<!-- parent_epic_file: <stub> -->` metadata comment in their parsed | ||
| files; the script uses this to route each child to its parent Epic's | ||
| filed key at filing time. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Clarify what <stub> means in the metadata comment.
Line 42 mentions <!-- parent_epic_file: <stub> --> but does not explicitly define what <stub> represents. Based on context (line 76 checks if it "points at an existing Epic file"), it appears to be a file stem or path component. A one-sentence clarification would help users understand the expected format.
✏️ Example clarification
You could add after line 42:
(where `<stub>` is the filename stem of the Epic file, e.g., `epic-name` for the file `epic-name.md`)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/file-jiras.md around lines 42 - 44, The documentation for
the parent_epic_file metadata comment does not explicitly explain what <stub>
represents. Add a one-sentence clarification after line 42 in the file-jiras.md
document explaining that <stub> is the filename stem of the Epic file (for
example, epic-name for a file named epic-name.md), so users understand the
expected format for the metadata comment pattern.
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
1 participant
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.
Description
Claude commands to file Jiras
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Summary by CodeRabbit