Back to Details

specstory-organize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SpecStory Organize

SpecStory 历史整理

Organizes your 
.specstory/history
directory by moving session files into 
YYYY/MM/
subdirectories based on the timestamp in each filename.
将你的
.specstory/history
目录中的会话文件，根据文件名中的时间戳移动到
YYYY/MM/
子目录中。

How It Works

工作原理

  1. Scans 
    .specstory/history/
    for markdown files
  2. Extracts the date from filenames (e.g., 
    2026-01-22_19-20-56Z-fix-bug.md
    )
  3. Creates year/month folders (e.g., 
    2026/01/
    )
  4. Moves files into the appropriate subdirectory
  5. Reports what was moved
  1. 扫描
    .specstory/history/
    目录下的markdown文件
  2. 提取文件名中的日期（例如：
    2026-01-22_19-20-56Z-fix-bug.md
    ）
  3. 创建年/月文件夹（例如：
    2026/01/
    ）
  4. 移动文件到对应的子目录
  5. 报告已移动的文件

Why Organize?

为什么需要整理？

Over time, your history directory can accumulate hundreds of session files. Organizing by date makes it easier to:
  • Find sessions from a specific time period
  • Archive old sessions
  • Keep your project directory clean
随着时间推移，你的历史目录会积累数百个会话文件。按日期整理后，你可以更轻松地：
  • 查找特定时间段的会话
  • 归档旧会话
  • 保持项目目录整洁

Usage

使用方法

Slash Command

斜杠命令

User saysAction
/specstory-organize
Organize all files (default)
/specstory-organize dry run
Preview changes without moving
/specstory-organize --dry-run
Preview changes without moving
用户指令操作
/specstory-organize
整理所有文件（默认）
/specstory-organize dry run
预览更改但不实际移动文件
/specstory-organize --dry-run
预览更改但不实际移动文件

Direct Script Usage

直接运行脚本

bash
undefined
bash
undefined

From project root

从项目根目录运行

python skills/specstory-organize/scripts/organize.py
python skills/specstory-organize/scripts/organize.py

Preview what would be moved (no changes made)

预览将要移动的文件（不进行实际修改）

python skills/specstory-organize/scripts/organize.py --dry-run
undefined
python skills/specstory-organize/scripts/organize.py --dry-run
undefined

Output

运行输出

SpecStory History Organizer
===========================

Found 47 files to organize in .specstory/history/

Moving files:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  2026-01-22_19-20-56Z-add-feature.md -> 2026/01/
  2025-12-28_09-15-33Z-cleanup.md -> 2025/12/
  ...

Summary:
--------
Files moved: 47
  2026/01/: 23 files
  2025/12/: 18 files
  2025/11/: 6 files

Your history is now organized!
SpecStory History Organizer
===========================

Found 47 files to organize in .specstory/history/

Moving files:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  2026-01-22_19-20-56Z-add-feature.md -> 2026/01/
  2025-12-28_09-15-33Z-cleanup.md -> 2025/12/
  ...

Summary:
--------
Files moved: 47
  2026/01/: 23 files
  2025/12/: 18 files
  2025/11/: 6 files

Your history is now organized!

Dry Run Output

试运行输出

When using 
--dry-run
:
SpecStory History Organizer (DRY RUN)
=====================================

Would organize 47 files in .specstory/history/

Preview:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  ...

No files were moved. Run without --dry-run to apply changes.
当使用
--dry-run
参数时：
SpecStory History Organizer (DRY RUN)
=====================================

Would organize 47 files in .specstory/history/

Preview:
  2026-01-15_10-30-22Z-refactor-auth.md -> 2026/01/
  2026-01-15_14-22-01Z-fix-tests.md -> 2026/01/
  ...

No files were moved. Run without --dry-run to apply changes.

Present Results to User

向用户展示结果

After running the organize script:
  1. Confirm success - Tell the user how many files were organized
  2. Show the breakdown - List how many files went to each month
  3. Note any skips - If files couldn't be parsed (no date in filename), mention them
运行整理脚本后：
  1. 确认成功 - 告知用户已整理的文件数量
  2. 展示分类明细 - 列出每个月份的文件数量
  3. 说明跳过的文件 - 如果存在无法解析的文件（文件名中无日期），需提及这些文件

Example Response

示例回复

Done! I organized 47 session files in your `.specstory/history/` directory:

- **2026/01/**: 23 files
- **2025/12/**: 18 files
- **2025/11/**: 6 files

Your history files are now sorted by year and month, making it much easier
to find sessions from specific time periods.
Done! I organized 47 session files in your `.specstory/history/` directory:

- **2026/01/**: 23 files
- **2025/12/**: 18 files
- **2025/11/**: 6 files

Your history files are now sorted by year and month, making it much easier
to find sessions from specific time periods.

Notes

注意事项

  • Files without a recognizable date pattern in the filename are skipped
  • The script uses the filename timestamp, not the file's modification time
  • Already-organized files (in subdirectories) are not moved again
  • Compatible with Python 2.7+ and Python 3.x
  • 文件名中无可识别日期格式的文件会被跳过
  • 脚本使用文件名中的时间戳，而非文件的修改时间
  • 已整理到子目录中的文件不会被重复移动
  • 兼容Python 2.7+和Python 3.x版本