Skip to content

Claude commands to file Jiras #152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisnik merged 3 commits into from
Jun 17, 2026
Merged

Claude commands to file Jiras #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
01d6e64
Claude commands to file Jiras
tisnik Jun 17, 2026
0eb9a2d
JIRA-related scripts
tisnik Jun 17, 2026
5d3d6e1
Script to file Jiras
tisnik Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions .claude/commands/file-jiras.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
Parse proposed JIRAs from a spike doc and file them via the Jira API

@coderabbitai coderabbitai Bot Jun 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

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


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.
Comment on lines +42 to +44

@coderabbitai coderabbitai Bot Jun 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🧹 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.


**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).
Comment on lines +1 to +95

@coderabbitai coderabbitai Bot Jun 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

🧩 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)"
fi

Repository: 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 -20

Repository: 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.

11 changes: 11 additions & 0 deletions dev-tools/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Development Tools

This directory contains utilities and tools for local development and testing of Lightspeed Core Stack.

## Adding New Tools

When adding new development tools to this directory:
1. Create a subdirectory for the tool
2. Include a README.md explaining what it does and how to use it
3. Update this file to list the new tool
4. Keep tools self-contained with their own dependencies (if any)
Loading
Loading