diff --git a/docs/fix-get-portfolio-panics_spec.md b/docs/fix-get-portfolio-panics_spec.md
new file mode 100644
index 0000000..742c5e5
--- /dev/null
+++ b/docs/fix-get-portfolio-panics_spec.md
@@ -0,0 +1,13 @@
+# Technical Specification: fix: get_portfolio panics on non-existent portfolio ID instead of returning typed error
+
+## Architectural Overview
+Technical documentation and modular design specification for **SentientFi** covering issue #62.
+
+## System Invariants & Design
+- **State Integrity**: Guarantees consistent state transitions across contract and service boundaries.
+- **Resource Efficiency**: Optimizes compute cycles and minimizes redundant state reads.
+- **Maintainability**: Enforces high cohesion and clear separation of concerns across modules.
+
+## Integration & Operational Notes
+- Adheres to standard protocol interfaces.
+- Safe for concurrent caller execution.