takt-optimize

TAKT Optimizer

Execute optimization of existing TAKT workflows. Diagnosis and analysis are handled by takt-analyze.

Prerequisite takt version: v0.30.0

Reference materials

Material	Path	Purpose
YAML schema	references/takt/builtins/skill/references/yaml-schema.md	Piece structure validation criteria
Engine specification	references/takt/builtins/skill/references/engine.md	Understanding prompt construction and token consumption
Style guide group	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet size limits
Built-in piece	references/takt/builtins/ja/pieces/	Reference for optimization patterns
Built-in facet	references/takt/builtins/ja/{personas,policies,instructions,knowledge,output-contracts}/	Built-in replacement candidates

Differences from takt-analyze

Perspective	takt-analyze	takt-optimize
Purpose	Problem detection, diagnosis, and reporting	Execution of optimization
Output	Analysis report (Markdown)	Optimized file group
Changes	None (read-only)	Directly edit and generate files
Input	Piece YAML + facets + execution logs	Piece YAML + facet + takt-analyze diagnostic results
Judgment	Problem severity classification	Cost/quality trade-off judgment
Log analysis	Execute it yourself and generate a diagnostic report	Use takt-analyze diagnostic results

Recommended flow: takt-analyze(Diagnosis) → based on its results, takt-optimize(optimization execution)

Optimization categories

1. Token consumption reduction

Reduce the token volume during prompt construction.

Engine prompt construction order (see: engine.md):

ペルソナ → ポリシー → コンテキスト → ナレッジ → インストラクション
→ タスク → 前回出力 → レポート指示 → タグ指示 → ポリシーリマインダー

Note: Policies are injected twice, at the beginning and at the end (as a countermeasure against Lost in the Middle). Policy bloat doubles token consumption.

Optimization	Method	Effect
Persona compression	Removal of redundant descriptions, compression within size limits	Reduction in each movement
Policy splitting	Split huge policies by purpose and assign them only to the necessary movements	Double effect (for the reminder portion)
Knowledge narrowing	Remove knowledge references unnecessary for the movement	Reduction of unnecessary context
Instruction simplification	Remove manual descriptions of automatically injected content	Deduplication
Output contract slimming	Compress output contracts exceeding 30 lines	Reduce in the report instruction section

Facet size guideline:

Facet	Recommended	Upper limit
Persona (simple)	30-50 lines	100 lines
Persona (expert)	50-300 lines	550 lines
Policy	60-250 lines	300 lines
Instruction (review)	5-12 lines	-
Instruction (plan/fix)	10-20 lines	-
Instruction (implement)	30-50 lines	-
Output Contract	10-25 lines	30 lines

2. Movement consolidation

Consolidate unnecessary movements to reduce the total number of steps in the workflow.

Pattern	Detection condition	Optimization
Consecutive identical personas	Adjacent movements have the same persona	Consolidate into 1 movement
Single-rule transition	There is 1 rule and the transition is unconditional	Consider consolidation with the preceding and following movements
edit=false chain	Chain of read-only movements	Evaluate the possibility of consolidation

Consolidation criteria:

• Whether the persona is the same or different between movements
• Whether the session: refresh boundary is not broken
• Whether independence of report output is required
• Whether rule branching is substantially meaningful

3. Rule simplification

Optimize rule conditions.

Optimization	Before	After
ai() → tag replacement	ai("実装が完了した")	"実装完了" (tag-based)
Remove unreachable rules	One of the 3 conditions is unreachable	Delete the unreachable rule
Shorten condition text	"全てのレビュアーが承認した"	"approved"

ai() vs tag-based decision:

• Tag-based (recommended): when results can be clearly classified
• ai(): only when context understanding is required for the decision

4. Facet reuse

Replace custom facets with built-ins and reduce the section map.

Procedure:

1. List the custom facets in the section map
2. Read the contents of each custom facet
3. Compare with built-in facets and evaluate similarity
4. If replaceable, replace with a bare name reference

Built-in replacement example:

# Before: カスタムファセットをセクションマップで参照
personas:
  my-coder: ../personas/my-coder.md
movements:
  - name: implement
    persona: my-coder

# After: ビルトインのbare name参照
movements:
  - name: implement
    persona: coder    # ビルトインを直接参照

Conditions under which replacement is not possible:

• Personas containing domain knowledge not present in built-ins
• Policies containing project-specific decision criteria
• Instructions containing proprietary procedures

5. Loop control improvement

Improve the efficiency and safety of the correction loop.

Optimization	Content
Add loop_monitors	Add a loop_monitor to the review→fix cycle if there is none
Convert instruction_template to a template reference	Replace inline text instruction_template with built-in facet reference (v0.30.0~)
threshold adjustment	Suggest appropriate values when threshold is too high/too low
Add ABORT condition	Add when there is no ABORT transition on failure
max_movements adjustment	Adjust when max_movements is excessive/insufficient relative to the number of movements
Fix supervise failure transition	supervise Change the rule that transitions to plan on failure to fix .supervise → plan The loop tends to be costly and unproductive
Add edit=false build prohibition	edit: false Add a prohibition section (## やらないこと) stating "Do not execute build commands" to the instruction referenced by the movement of

Recommended threshold value:

• review→fix cycle: 3 times
• supervise→fix cycle: 3 times
• implement→test cycle: 2 times

6. Parallelization proposal

Detect movements that are executed sequentially but can be parallelized.

Parallelization conditions:

• Do not reference each other's output (pass_previous_response not needed)
• Use the report of the same previous movement as input
• Output independent reports

# Before: 逐次レビュー
- name: arch-review
  ...
  rules:
    - condition: done
      next: qa-review
- name: qa-review
  ...

# After: 並列レビュー
- name: reviewers
  parallel:
    - name: arch-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
    - name: qa-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
  rules:
    - condition: all("approved")
      next: supervise
    - condition: any("needs_fix")
      next: fix

7. Optimization based on log diagnosis results

Using takt-analyze log diagnosis results as input, execute optimization based on actual data.

Prerequisite: Reading, analyzing, and diagnosing logs is handled by takt-analyze. In this category, only "what to change" is handled based on the diagnosis results.

Diagnosis result → Optimization action:

takt-analyze diagnosis	Optimization action
Loop hotspot (Warning/Critical)	loop_monitor の threshold adjustment, review of rule conditions
Dead rule (Critical)	Removal of unreachable rules
Low rule evaluation efficiency (ai_judge_fallback high frequency)	Rewrite to tag-based rules, add tag output instructions to output-contract
High ABORT rate	Flow improvement according to the ABORT cause reason (max_movements adjustment, addition of ABORT conditions)
Repeated errors by phase	Improvement of instructions and personas for error-prone phases
Low iteration efficiency	max_movements Calculation of appropriate values, consideration of movement integration

Workflow

Step 1: Identify and load the target

Identify the target piece YAML and load all related facets.

探索順序:
1. ユーザー指定のパス
2. ~/.takt/pieces/ 内のカスタムピース
3. .takt/pieces/ 内のプロジェクトピース

Content to load:

• The entire piece YAML
• All facet files of the section map
• Built-in facets (for comparison)
• takt-analyze diagnosis report (if provided)

Step 2: Create optimization plan

Evaluate the optimization potential of each category and present a plan.

# 最適化プラン: {ピース名}

## 分析ソース
- 静的分析: ピースYAML + ファセット{N}件
- takt-analyze診断: {診断レポートの要約}（提供された場合）

## 推定効果
- トークン削減: 約{N}%
- ムーブメント数: {before} → {after}
- ファイル数: {before} → {after}

## 最適化項目
| # | カテゴリ | 対象 | 内容 | 根拠 | リスク |
|---|---------|------|------|------|--------|
| 1 | トークン削減 | persona/coder | 120行→80行に圧縮 | 静的 | 低 |
| 2 | ビルトイン置換 | persona/my-reviewer | → architecture-reviewer | 静的 | 低 |
| 3 | ルール簡素化 | ai_review | ai_fallback 67% → タグ化 | 診断 | 低 |
| 4 | 並列化 | arch-review + qa-review | 逐次→並列 | 静的 | 中 |

Confirm with user: Present the plan and obtain approval for the items to execute.

Decision flow:

• 0 optimization items → report "Already sufficiently optimized" and end
• User approves some → execute only approved items in Step 3
• User rejects all → end

Step 3: Execute optimization

Execute the approved items.

Execution order (dependency order):

1. Facet compression/integration (changes to file contents)
2. Built-in replacement (changes to section map)
3. Movement integration (changes to YAML structure)
4. Rule simplification (changes to rule conditions)
5. Loop control improvement (adding loop_monitors)
6. Parallelization (major changes to movement structure)

Step 4: Consistency verification

Verify the consistency of the file group after optimization.

• Section map keys and in-movement references match
• Section map paths point to files that actually exist
• initial_movementがmovementsexists in the array
• All rules'nextis a valid transition destination
• parallel parent ruleall()/any()uses
• In the rule of the parallel substep,nextis missing
• Facets are within size limits
• No references to deleted facets remain

Step 5: Result report

# 最適化結果: {ピース名}

## サマリー
- トークン削減: 約{N}%（推定）
- ムーブメント数: {before} → {after}
- ファイル数: {before} → {after}

## 変更一覧
| # | ファイル | 変更内容 |
|---|---------|---------|
| 1 | pieces/my-piece.yaml | ムーブメント統合、ルール簡素化 |
| 2 | personas/coder.md | 120行→80行に圧縮 |
| 3 | (削除) personas/my-reviewer.md | ビルトインに置換 |

## 削除ファイル
- personas/my-reviewer.md（→ ビルトイン architecture-reviewer で代替）

## 注意事項
{最適化による動作変更の可能性がある場合に記載}

Validation

Created/edited files can be mechanically verified with validate-takt-files.sh :

bash .agents/skills/takt-optimize/scripts/validate-takt-files.sh

Verification items:

• Piece YAML: Required fields (name/initial_movement/movements）、initial_movement movement references, existence of facet file references
• Facet .md: Empty check, persona/policy/knowledge require # 見出し , instruction/output-contract require content presence

Option --pieces / --facets You can narrow down targets with.