innoq · feststelltaste · May 30, 2025
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# AIMER: AI-Assisted Software Analysis & Improvement Prompts
+# AIMER: Experiments on AI-Assisted Software Analysis & Improvements
 
 <div align="center">
     <img src="aimer.webp" alt="Illustration of a wooden catapult with a smiling face aimed at a stone castle tower, with colorful bandages floating above, representing AIMER's approach to fixing and improving software systems" width="50%">
@@ -53,12 +53,29 @@ We believe AI can become a true partner in software modernization — not by rep
 
 AIMER provides battle-tested methodologies and structured approaches for software analysis and improvement, leveraging years of practical experience in software architecture and development. These aren't just prompts – they're distilled little frameworks based on solid foundations from industry expertise and proven practices.
 
-Each command represents a specific analytical methodology designed to systematically examine different aspects of your software systems: from identifying architectural hotspots and documenting decisions to analyzing stakeholder needs and security concerns.
+Each command represents a specific analytical methodology designed to systematically examine different aspects of your software systems: from identifying architectural hotspots and documenting decisions to challenging security concerns and the original stakeholder needs and assumptions.
 
 
-## Use with Claude Code
+## Current Status 
 
-You may use these prompts wherever you like. 
+We're working in public to explore what's currently possible with AI-assisted architecture development and legacy system modernization together with you!
+
+For this, we've created several commands for Claude Code and are using a lightweight process, mapped to three directories:
+
+* `ideas`: Early-stage prompts and concepts, many inspired by resources like the *aim42* guide or the book *Software Reviews*. Some suggestions may not make sense yet and possible to implement with today's technologies, but we'll refine and filter them over time. See the contents of this directory more like an initial brainstorming.
+
+* `experiments`: More developed ideas and commands we're actively testing. They're absolutely not production-ready, but first developers are working on those to evolve them into something that could actually work. Here we especially welcome discussions and feedback to improve their robustness and usefulness.
+
+* `commands`: Stable prompts that work reliably and help answer architectural questions, especially in real-world legacy modernization scenarios.
+
+Depending on your goals, copy the commands you want to work on into Claude Code's `commands` directory or add new ideas directly to the repository with a Pull Request.
+
+
+## Current Approach
+
+We're using Claude Code as starting point for our first experiments in this area to avoid creating something that will be obsolete with the next iteration of AI assistents.
+
+You may use these prompts wherever you like.
 We’ll document a way to use them as [custom slash commands in Claude Code](https://docs.anthropic.com/en/docs/claude-code/tutorials#create-custom-slash-commands):
 
 ### Project-Specific Commands

diff --git a/commands/adr-documentation-parallel.md → experiments/adr-documentation-parallel.md b/commands/adr-documentation-parallel.md → experiments/adr-documentation-parallel.md
diff --git a/commands/adr-parallel-consolidator.md → experiments/adr-parallel-consolidator.md b/commands/adr-parallel-consolidator.md → experiments/adr-parallel-consolidator.md
diff --git a/commands/adr-parallel-data-api-analyzer.md → ...riments/adr-parallel-data-api-analyzer.md b/commands/adr-parallel-data-api-analyzer.md → ...riments/adr-parallel-data-api-analyzer.md
diff --git a/...ands/adr-parallel-existing-adr-scanner.md → ...ents/adr-parallel-existing-adr-scanner.md b/...ands/adr-parallel-existing-adr-scanner.md → ...ents/adr-parallel-existing-adr-scanner.md
diff --git a/commands/adr-parallel-history-analyzer.md → experiments/adr-parallel-history-analyzer.md b/commands/adr-parallel-history-analyzer.md → experiments/adr-parallel-history-analyzer.md
diff --git a/...s/adr-parallel-infrastructure-analyzer.md → ...s/adr-parallel-infrastructure-analyzer.md b/...s/adr-parallel-infrastructure-analyzer.md → ...s/adr-parallel-infrastructure-analyzer.md
diff --git a/commands/adr-parallel-static-analyzer.md → experiments/adr-parallel-static-analyzer.md b/commands/adr-parallel-static-analyzer.md → experiments/adr-parallel-static-analyzer.md
diff --git a/commands/adr.md → experiments/adr.md b/commands/adr.md → experiments/adr.md
diff --git a/commands/adr_documentation.md → experiments/adr_documentation.md b/commands/adr_documentation.md → experiments/adr_documentation.md
diff --git a/commands/c4-documentation-parallel.md → experiments/c4-documentation-parallel.md b/commands/c4-documentation-parallel.md → experiments/c4-documentation-parallel.md
diff --git a/commands/c4-parallel-consolidation.md → experiments/c4-parallel-consolidation.md b/commands/c4-parallel-consolidation.md → experiments/c4-parallel-consolidation.md
diff --git a/...ands/c4-parallel-documentation-scanner.md → ...ents/c4-parallel-documentation-scanner.md b/...ands/c4-parallel-documentation-scanner.md → ...ents/c4-parallel-documentation-scanner.md
diff --git a/commands/c4-parallel-git-history-analyzer.md → ...ments/c4-parallel-git-history-analyzer.md b/commands/c4-parallel-git-history-analyzer.md → ...ments/c4-parallel-git-history-analyzer.md
diff --git a/...ds/c4-parallel-infrastructure-analyzer.md → ...ts/c4-parallel-infrastructure-analyzer.md b/...ds/c4-parallel-infrastructure-analyzer.md → ...ts/c4-parallel-infrastructure-analyzer.md
diff --git a/commands/c4-parallel-static-code-analyzer.md → ...ments/c4-parallel-static-code-analyzer.md b/commands/c4-parallel-static-code-analyzer.md → ...ments/c4-parallel-static-code-analyzer.md
diff --git a/commands/c4_documentation.md → experiments/c4_documentation.md b/commands/c4_documentation.md → experiments/c4_documentation.md
diff --git a/commands/doc-readmes.md → experiments/doc-readmes.md b/commands/doc-readmes.md → experiments/doc-readmes.md
diff --git a/commands/architecture-conformity.md → ideas/architecture-conformity.md b/commands/architecture-conformity.md → ideas/architecture-conformity.md
diff --git a/commands/code-walkthrough.md → ideas/code-walkthrough.md b/commands/code-walkthrough.md → ideas/code-walkthrough.md
diff --git a/commands/context-analysis.md → ideas/context-analysis.md b/commands/context-analysis.md → ideas/context-analysis.md
diff --git a/commands/data-analysis.md → ideas/data-analysis.md b/commands/data-analysis.md → ideas/data-analysis.md
diff --git a/...nds/deployment-infrastructure-analysis.md → ideas/deployment-infrastructure-analysis.md b/...nds/deployment-infrastructure-analysis.md → ideas/deployment-infrastructure-analysis.md
diff --git a/...lysis-parallel-business-logic-analyzer.md → ...lysis-parallel-business-logic-analyzer.md b/...lysis-parallel-business-logic-analyzer.md → ...lysis-parallel-business-logic-analyzer.md
diff --git a/...-analysis-parallel-complexity-analyzer.md → ...-analysis-parallel-complexity-analyzer.md b/...-analysis-parallel-complexity-analyzer.md → ...-analysis-parallel-complexity-analyzer.md
diff --git a/...hotspot-analysis-parallel-consolidator.md → ...hotspot-analysis-parallel-consolidator.md b/...hotspot-analysis-parallel-consolidator.md → ...hotspot-analysis-parallel-consolidator.md
diff --git a/...analysis-parallel-git-history-analyzer.md → ...analysis-parallel-git-history-analyzer.md b/...analysis-parallel-git-history-analyzer.md → ...analysis-parallel-git-history-analyzer.md
diff --git a/...spot-analysis-parallel-impact-analyzer.md → ...spot-analysis-parallel-impact-analyzer.md b/...spot-analysis-parallel-impact-analyzer.md → ...spot-analysis-parallel-impact-analyzer.md
diff --git a/...otspot-analysis-parallel-team-analyzer.md → ...otspot-analysis-parallel-team-analyzer.md b/...otspot-analysis-parallel-team-analyzer.md → ...otspot-analysis-parallel-team-analyzer.md
diff --git a/commands/hotspot-analysis-parallel.md → ideas/hotspot-analysis-parallel.md b/commands/hotspot-analysis-parallel.md → ideas/hotspot-analysis-parallel.md
diff --git a/commands/hotspot-analysis.md → ideas/hotspot-analysis.md b/commands/hotspot-analysis.md → ideas/hotspot-analysis.md
diff --git a/commands/process-analysis.md → ideas/process-analysis.md b/commands/process-analysis.md → ideas/process-analysis.md
diff --git a/commands/quality-scenario-analysis.md → ideas/quality-scenario-analysis.md b/commands/quality-scenario-analysis.md → ideas/quality-scenario-analysis.md
diff --git a/commands/root-cause-analysis.md → ideas/root-cause-analysis.md b/commands/root-cause-analysis.md → ideas/root-cause-analysis.md
diff --git a/commands/security-analysis.md → ideas/security-analysis.md b/commands/security-analysis.md → ideas/security-analysis.md
diff --git a/commands/stakeholder-interviews.md → ideas/stakeholder-interviews.md b/commands/stakeholder-interviews.md → ideas/stakeholder-interviews.md
diff --git a/commands/static-code-analysis.md → ideas/static-code-analysis.md b/commands/static-code-analysis.md → ideas/static-code-analysis.md